wholable 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42f00bcfb8063a21a4fb8f6427424078be9ce45365d2b41f5a6c053133b059d7
-  data.tar.gz: 267014e8011488d2b9e3db0fcdecebe6a70c0032e8f47ea60cb0d3b035174719
+  metadata.gz: 926e2edcbc46f6bc80713ffcabfbcfcc7e0863ecfca039bb43aae8d79aca7727
+  data.tar.gz: 1b3bee9c9eeaaf4f3e3addcde40f1e49912533cb50ca0f7348bc988050da75f3
 SHA512:
-  metadata.gz: 94334fe408aa2e6ac16589688f1c3e3a4d746f738ef9ec4c75d2031e10898463ce63954e0c8f147167396a0a18da79d312a75a5a3ce52bc663a773be824841d9
-  data.tar.gz: b921837f4c80fb2651cf6a135c367c0fd2bbf18a5dfa47c0ad52838ad6f6482b90492e18d312093660f2f4ee693f56c49768647b50c8f7e0b5c93d0a9d99c9d7
+  metadata.gz: 46e3d952fed95ffc62afc158c93c802e38445b1bea62c8ff80c0edc28c4b699435bd41081d48a047d93e84d746e3a094596f58055e0207bdfdf8cfaf9292452f
+  data.tar.gz: 9baf38439f8ad831639f29ce8722bcda20b941a14b78330917c3efd6b1a33c713001562cbf5cc3643025fb4a5305d4b3742fe9444b57fa34a779d65b9d546dca

data/README.adoc

@@ -3,10 +3,16 @@
 :figure-caption!:
 
 :data_link: link:https://alchemists.io/articles/ruby_data[Data]
+:ruby_link: link:https://www.ruby-lang.org[Ruby]
+:structs_link: link:https://alchemists.io/articles/ruby_structs[Structs]
 
 = Wholable
 
-Wholable is a mixin that turns a class into a _whole value object_ by ensuring object equality is determined by the values that make up the object instead of by identity within memory.
+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]:
+
+* 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.
+* Value objects should be immutable (i.e. frozen) by default. This implementation enforces a strict adherence to immutability in order to ensure value objects remain equal and discourage mutation.
 
 toc::[]
 
@@ -19,7 +25,7 @@ toc::[]
 
 == Requirements
 
-. link:https://www.ruby-lang.org[Ruby].
+. {ruby_link}.
 
 == Setup
 
@@ -72,6 +78,9 @@ 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.frozen?          # true
 jill_two.frozen?      # true
 jack.frozen?          # true
@@ -80,9 +89,6 @@ jill.inspect          # "#<Person @name=\"Jill Smith\", @email=\"jill@example.co
 jill_two.inspect      # "#<Person @name=\"Jill Smith\", @email=\"jill@example.com\">"
 jack.inspect          # "#<Person @name=\"Jack Smith\", @email=\"jack@example.com\">"
 
-jill.name             # "Jill Smith"
-jill.email            # "jill@example.com"
-
 jill == jill          # true
 jill == jill_two      # true
 jill == jack          # false
@@ -100,17 +106,18 @@ jill_two.hash         # 3650965837788801745
 jack.hash             # 4460658980509842640
 ----
 
-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:
+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 will be created which saves you time and reduces double entry.
-. The object will be immediately frozen after initialization to ensure your instance is _immutable_ by default.
+. 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 object is immediately frozen after initialization to ensure your instance is _immutable_ by default.
 
 == Caveats
 
-The whole value contract created for you when using this gem can be broken by doing the following:
+Whole values can be broken via the following:
 
-* *Duplication*: Sending the `#dub` 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 contract so ensure you let Wholable manage this for you.
+* *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.
 * *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
@@ -118,8 +125,9 @@ The whole value contract created for you when using this gem can be broken by do
 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. A version of this has moved into link:https://dry-rb.org/gems/dry-core[Dry Core] but doesn't appear to work properly or be well supported. Even the documentation is not fully linked on the main page.
-- 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 now.
+- 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
 

data/lib/wholable/equatable.rb

@@ -38,7 +38,6 @@ module Wholable
       end
     end
 
-    # :reek:TooManyStatements
     def define_inspect
       local_keys = keys
 
@@ -46,7 +45,7 @@ module Wholable
         klass = self.class
         name = klass.name || klass.inspect
 
-        local_keys.map { |key| %(@#{key}=#{public_send(key).inspect}) }
+        local_keys.map { |key| "@#{key}=#{public_send(key).inspect}" }
                   .join(", ")
                   .then { |pairs| "#<#{name} #{pairs}>" }
       end

data/lib/wholable/freezable.rb

@@ -4,7 +4,7 @@ module Wholable
   # Ensures an object is frozen after being initialized.
   module Freezable
     def initialize(...)
-      super(...)
+      super
       freeze
     end
   end

data/wholable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "wholable"
-  spec.version = "0.0.0"
+  spec.version = "0.0.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.0
+  version: 0.0.1
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-07-27 00:00:00.000000000 Z
+date: 2023-08-06 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.17
+rubygems_version: 3.4.18
 signing_key:
 specification_version: 4
 summary: A whole value object mixin.