wholable 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 926e2edcbc46f6bc80713ffcabfbcfcc7e0863ecfca039bb43aae8d79aca7727
-  data.tar.gz: 1b3bee9c9eeaaf4f3e3addcde40f1e49912533cb50ca0f7348bc988050da75f3
+  metadata.gz: 72a28b3df96aec9ab54375e96583424bc919c9659b2f701ab600b341d82d61b9
+  data.tar.gz: 898361fe5766c92fc629b7ea3d459576a902369f09fe438f3c7e5cc76ed93bf3
 SHA512:
-  metadata.gz: 46e3d952fed95ffc62afc158c93c802e38445b1bea62c8ff80c0edc28c4b699435bd41081d48a047d93e84d746e3a094596f58055e0207bdfdf8cfaf9292452f
-  data.tar.gz: 9baf38439f8ad831639f29ce8722bcda20b941a14b78330917c3efd6b1a33c713001562cbf5cc3643025fb4a5305d4b3742fe9444b57fa34a779d65b9d546dca
+  metadata.gz: a66ba09ec485373c4b3789203bf5a5d72d4d5438d33668f4981de9269b665ccbd81a5969f45da443149a377775762090d9926e826648b9a5f5fb5c7f72fc3d36
+  data.tar.gz: e0407f928f8310c4350a512ee087ab8c542ca66482cd2f2fc67c9cd996b4991aa53ac3c8ab2209c57429108b1ed743afb5f76b9ec43fc63249e0e7055e3bef0a

data/README.adoc

@@ -3,12 +3,14 @@
 :figure-caption!:
 
 :data_link: link:https://alchemists.io/articles/ruby_data[Data]
+:pattern_matching_link: link:https://alchemists.io/articles/ruby_pattern_matching[pattern matching]
 :ruby_link: link:https://www.ruby-lang.org[Ruby]
+:data_link: link:https://alchemists.io/articles/ruby_data[Data]
 :structs_link: link:https://alchemists.io/articles/ruby_structs[Structs]
 
 = Wholable
 
-Wholable is a mixin that allows you to turn your object into a _whole value object_ by ensuring object equality is determined by the values of the object instead of by identity. Whole value objects -- or value objects in general -- have the following traits as also noted via link:https://en.wikipedia.org/wiki/Value_object[Wikipedia]:
+Wholable allows you to turn your object into a _whole value object_ by ensuring object equality is determined by the values of the object instead of by identity. Whole value objects -- or value objects in general -- have the following traits as also noted via link:https://en.wikipedia.org/wiki/Value_object[Wikipedia]:
 
 * Equality is determined by the values that make up an object and not by link:https://en.wikipedia.org/wiki/Identity_(object-oriented_programming)[identity] (i.e. memory address) which is the default behavior for all {ruby_link} objects except for {data_link} and {structs_link}.
 * Identity remains unique since two objects can have the same values but different identity. This means `BasicObject#equal?` is never overwritten -- which is strongly discouraged -- as per link:https://rubyapi.org/o/basicobject#method-i-3D-3D[BasicObject] documentation.
@@ -19,6 +21,8 @@ toc::[]
 == Features
 
 * Ensures equality (i.e. `#==` and `#eql?`) is determined by attribute values and not object identity (i.e. `#equal?`).
+* Allows you to compare two objects of same or different types and see their differences.
+* Provides {pattern_matching_link}.
 * Automatically defines public attribute readers (i.e. `.attr_reader`) based on provided keys.
 * Ensures object inspection (i.e. `#inspect`) shows all registered attributes.
 * Ensures object is frozen upon initialization.
@@ -78,38 +82,56 @@ jill = Person.new name: "Jill Smith", email: "jill@example.com"
 jill_two = Person.new name: "Jill Smith", email: "jill@example.com"
 jack = Person.new name: "Jack Smith", email: "jack@example.com"
 
-jill.name             # "Jill Smith"
-jill.email            # "jill@example.com"
+jill.name              # "Jill Smith"
+jill.email             # "jill@example.com"
+
+jill.frozen?           # true
+jill_two.frozen?       # true
+jack.frozen?           # true
+
+jill.inspect           # "#<Person @name=\"Jill Smith\", @email=\"jill@example.com\">"
+jill_two.inspect       # "#<Person @name=\"Jill Smith\", @email=\"jill@example.com\">"
+jack.inspect           # "#<Person @name=\"Jack Smith\", @email=\"jack@example.com\">"
+
+jill == jill           # true
+jill == jill_two       # true
+jill == jack           # false
 
-jill.frozen?          # true
-jill_two.frozen?      # true
-jack.frozen?          # true
+jill.diff(jill)        # {}
+jill.diff(jack)        # {
+                       #   name: ["Jill Smith", "Jack Smith"],
+                       #   email: ["jill@example.com", "jack@example.com"]
+                       # }
+jill.diff(Object.new)  # {:name=>["Jill Smith", nil], :email=>["jill@example.com", nil]}
 
-jill.inspect          # "#<Person @name=\"Jill Smith\", @email=\"jill@example.com\">"
-jill_two.inspect      # "#<Person @name=\"Jill Smith\", @email=\"jill@example.com\">"
-jack.inspect          # "#<Person @name=\"Jack Smith\", @email=\"jack@example.com\">"
+jill.eql? jill         # true
+jill.eql? jill_two     # true
+jill.eql? jack         # false
 
-jill == jill          # true
-jill == jill_two      # true
-jill == jack          # false
+jill.equal? jill       # true
+jill.equal? jill_two   # false
+jill.equal? jack       # false
 
-jill.eql? jill        # true
-jill.eql? jill_two    # true
-jill.eql? jack        # false
+jill.hash              # 3650965837788801745
+jill_two.hash          # 3650965837788801745
+jack.hash              # 4460658980509842640
 
-jill.equal? jill      # true
-jill.equal? jill_two  # false
-jill.equal? jack      # false
+jill.to_a              # ["Jill Smith", "jill@example.com"]
+jack.to_a              # ["Jack Smith", "jack@example.com"]
 
-jill.hash             # 3650965837788801745
-jill_two.hash         # 3650965837788801745
-jack.hash             # 4460658980509842640
+jill.to_h              # {:name=>"Jill Smith", :email=>"jill@example.com"}
+jack.to_h              # {:name=>"Jack Smith", :email=>"jack@example.com"}
+
+jill.with name: "Sue"  # #<Person @name="Sue", @email="jill@example.com">
+jill.with bad: "!"     # unknown keyword: :bad (ArgumentError)
 ----
 
 As you can see, object equality is determined by the object's values and _not_ by the object's identity. When you include `Wholable` along with a list of keys, the following happens:
 
-. The corresponding _public_ `attr_reader` for each key is created which saves you time and reduces double entry.
-. Custom `#==`, `#eql?`, `#hash`, and `#inspect` methods are added to provide whole value behavior.
+. The corresponding _public_ `attr_reader` for each key is created which saves you time and reduces double entry when implementing your whole value object.
+. The `#to_a` and `#to_h` methods are added for convenience in order to play nice with {data_link} and {structs_link}.
+. The `#deconstruct` and `#deconstruct_keys` aliases are created for you so you can leverage {pattern_matching_link}.
+. Custom `#==`, `#eql?`, `#hash`, `#inspect`, `#to_a`, `#to_h`, and `#with` methods are added to provide whole value behavior.
 . The object is immediately frozen after initialization to ensure your instance is _immutable_ by default.
 
 == Caveats
@@ -117,18 +139,9 @@ As you can see, object equality is determined by the object's values and _not_ b
 Whole values can be broken via the following:
 
 * *Duplication*: Sending the `#dup` message will cause your whole value object to be unfrozen. This might be desired in certain situations but make sure to refreeze when able.
-* *Post Attributes*: Adding additional attributes after what is defined when including `Wholable` will break your whole value object. To prevent this, let Wholable manage this for you (easiest). Otherwise (harder), you can manually override `#==`, `#eql?`, `#hash`, and `#inspect` behavior at which point you probably don't need Wholable anymore.
+* *Post Attributes*: Adding additional attributes after what is defined when including `Wholable` will break your whole value object. To prevent this, let Wholable manage this for you (easiest). Otherwise (harder), you can manually override `#==`, `#eql?`, `#hash`, `#inspect`, `#to_a`, and `#to_h` behavior at which point you don't need Wholable anymore.
 * *Deep Freezing*: The automatic freezing of your instances is shallow and will not deeply freeze nested attributes. This behavior mimics the behavior of {data_link} objects.
 
-== Influences
-
-This implementation is based upon these original designs:
-
-- link:https://github.com/dkubb/equalizer[Equalizer]: One of the first implementations that is over a decade old and no longer maintained.
-- link:https://github.com/dry-rb/dry-equalizer[Dry Equalizer]: Deprecated and no longer maintained but was based upon the above implementation and has now moved into Dry Core.
-- link:https://dry-rb.org/gems/dry-core[Dry Core]: Includes the link:https://dry-rb.org/gems/dry-core/equalizer[Dry::Core::Equalizer] module which is officially supported and actively maintained by the Dry RB team. A good alternative to this gem.
-- link:https://github.com/piotrmurach/equatable/tree/master[Equatable]: A similar implementation to the above but is based off what you define via your `.attr_reader`. The project hasn't been maintained or updated in several years.
-
 == Development
 
 To contribute, run:

data/lib/wholable/comparable.rb

@@ -6,5 +6,14 @@ module Wholable
     def eql?(other) = instance_of?(other.class) && hash == other.hash
 
     def ==(other) = other.is_a?(self.class) && hash == other.hash
+
+    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

data/lib/wholable/equatable.rb

@@ -6,14 +6,13 @@ module Wholable
     def initialize *keys
       super()
       @keys = keys.uniq
-      define_hash
-      define_inspect
+      define_instance_methods
       freeze
     end
 
     def included descendant
       super
-      define_readers descendant
+      define_class_methods descendant
       descendant.include Comparable
       descendant.prepend Freezable
     end
@@ -22,12 +21,42 @@ module Wholable
 
     attr_reader :keys
 
+    def define_instance_methods
+      define_hash
+      define_inspect
+      define_with
+      define_to_a
+      define_to_h
+    end
+
+    def define_class_methods descendant
+      define_readers descendant
+      define_deconstruct descendant
+      define_deconstruct_keys descendant
+    end
+
     def define_readers descendant
       descendant.class_eval <<-READERS, __FILE__, __LINE__ + 1
         attr_reader #{keys.map(&:inspect).join ", "}
       READERS
     end
 
+    def define_deconstruct descendant
+      descendant.class_eval <<-READERS, __FILE__, __LINE__ + 1
+        alias deconstruct to_a
+      READERS
+    end
+
+    def define_deconstruct_keys descendant
+      descendant.class_eval <<-READERS, __FILE__, __LINE__ + 1
+        alias deconstruct_keys to_h
+      READERS
+    end
+
+    def define_with
+      define_method(:with) { |**attributes| self.class.new(**to_h.merge!(attributes)) }
+    end
+
     def define_hash
       local_keys = keys
 
@@ -50,5 +79,21 @@ module Wholable
                   .then { |pairs| "#<#{name} #{pairs}>" }
       end
     end
+
+    def define_to_a
+      local_keys = keys
+
+      define_method :to_a do
+        local_keys.reduce([]) { |array, key| array.append public_send(key) }
+      end
+    end
+
+    def define_to_h
+      local_keys = keys
+
+      define_method :to_h do
+        local_keys.each.with_object({}) { |key, dictionary| dictionary[key] = public_send key }
+      end
+    end
   end
 end

data/wholable.gemspec

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wholable
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-08-06 00:00:00.000000000 Z
+date: 2023-10-26 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -79,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.18
+rubygems_version: 3.4.21
 signing_key:
 specification_version: 4
 summary: A whole value object mixin.