wholeable 0.0.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7170fd4f95494351863b4ef31203f38ec10ae4d7a589691fb50e38ca813cbbb6
-  data.tar.gz: 020a94f04704a611cf55a371830d3ee4a8f7cfccb11e9ab3c31c782b830145b7
+  metadata.gz: bea89015c8fa8dc330ce5b460023efcf2ba0d7f5c588b3bcc7109c60cbd5194b
+  data.tar.gz: 2448e7f7134b72e46d5a66390051b13707a3fce2e3880bdea29db2e931e1a45c
 SHA512:
-  metadata.gz: 6d307cf89e4a8ba694c20bdd4fb5afc92fd93fce6a98bc0dd77df7c58f9bf5cd3da11d96be41479d176806a66ae3b2864d3a6d9078d855ffeaf29ac8be1ca675
-  data.tar.gz: 9e4a70b92a5cb656a8ea4aaf874eff0050166811c295cf91d0fc305974a2c73604cefb80bc3eac4c868971ffeabee32de835f76c9e40d745988ca66e9ba84fe4
+  metadata.gz: 21bbd3f36b3e649a22127e7ad9648a5d75922fd970e2db40feb50e14c606d34fc1ac4cdb14c31d2d8246aabc747f7e296e28ab08e3bfa801351e590c495b4f53
+  data.tar.gz: e80fb760af6edb13340786236f53869c5b22a2a57e641cc08bab633ee5187125f179583b1b33ec2d6a893b3228da97928691c7e268e3fca420ed333726773ee6

data/README.adoc

@@ -23,9 +23,10 @@ toc::[]
 * 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.
+* Provides inheritance so you can subclass and add attributes or provide additional behavior.
+* Automatically defines public attribute readers (i.e. `.attr_reader`) if _immutable_ (default) or public attribute readers and writers (i.e. `.attr_accessor`) if _mutable_.
 * Ensures object inspection (i.e. `#inspect`) shows all registered attributes.
-* Ensures object is frozen upon initialization.
+* Ensures object is frozen upon initialization by default.
 
 == Requirements
 
@@ -78,9 +79,12 @@ class Person
   end
 end
 
-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 = Person[name: "Jill Smith", email: "jill@example.com"]
+jill_two = Person[name: "Jill Smith", email: "jill@example.com"]
+jack = Person[name: "Jack Smith", email: "jack@example.com"]
+
+Person.members         # [:name, :email]
+jill.members           # [:name, :email]
 
 jill.name              # "Jill Smith"
 jill.email             # "jill@example.com"
@@ -122,25 +126,217 @@ jack.to_a              # ["Jack Smith", "jack@example.com"]
 jill.to_h              # {:name=>"Jill Smith", :email=>"jill@example.com"}
 jack.to_h              # {:name=>"Jack Smith", :email=>"jack@example.com"}
 
+jill.to_s              # "#<Person @name=\"Jill Smith\", @email=\"jill@example.com\">"
+jill_two.to_s          # "#<Person @name=\"Jill Smith\", @email=\"jill@example.com\">"
+jack.to_s              # "#<Person @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 `Wholeable` 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 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 corresponding _public_ `attr_reader` (or `attr_accessor` if mutable) for each key is created which saves you time and reduces double entry when implementing your whole value object.
+. The `#to_a`, `#to_h`, and `#to_s` methods are added for convenience and to be compatible with {data_link} and {structs_link}.
 . The `#deconstruct` and `#deconstruct_keys` aliases are created so you can leverage {pattern_matching_link}.
 . The `#==`, `#eql?`, `#hash`, `#inspect`, 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.
 
+=== Initialization
+
+As shown above, you can create an instance of your whole value object by using `.[]`. Example:
+
+[source,ruby]
+----
+Person[name: "Jill Smith", email: "jill@example.com"]
+----
+
+Alternatively, you can create new instances using `.new`. Example:
+
+[source,ruby]
+----
+Person.new name: "Jill Smith", email: "jill@example.com"
+----
+
+Both methods work but use `.[]` when supplying arguments and `.new` when you don't have any arguments.
+
+=== Mutability
+
+All whole value objects are frozen by default. You can change behavior by specifying whether instances should be mutable by passing `kind: :mutable` as a keyword argument. Example:
+
+[source,ruby]
+----
+class Person
+  include Wholeable[:name, :email, kind: :mutable]
+
+  def initialize name: "Jill", email: "jill@example.com"
+    @name = name
+    @email = email
+  end
+end
+
+jill = Person.new
+jill.frozen? # false
+----
+
+When your object is mutable, you'll also have access to setter methods in addition to the normal getter methods. Example:
+
+[source,ruby]
+----
+jill.name # "Jill"
+jill.name = "Jayne"
+jill.name # "Jayne"
+----
+
+You can also make your object immutable by using `kind: :immutable` but this is default behavior and redundant. Any invalid kind (example: `kind: :bogus`) will be ignored and default to being immutable.
+
+=== Inheritance
+
+Unlike {data_link} or {structs_link}, you can subclass a whole value object. Example:
+
+[source,ruby]
+----
+class Person
+  include Wholeable[:name]
+
+  def initialize name:
+    @name = name
+  end
+end
+
+class Contact < Person
+  include Wholeable[:email]
+
+  def initialize(email:, **)
+    super(**)
+    @email = email
+  end
+end
+
+contact = Contact[name: "Jill Smith", email: "jill@example.com"]
+
+contact.to_h     # {name: "Jill Smith", email: "jill@example.com"}
+contact.frozen?  # true
+----
+
+Notice `Contact` inherits from `Person` while only defining the attributes that make it unique. You don't need to redefine the same attributes found in the superclass as that would be redundant and defeat the purpose of subclassing in the first place.
+
+When subclassing, each subclass has access to the same attributes defined by the superclass no matter how deep your ancestry is. This does mean you must pass the remaining attributes to the superclass via the double splat.
+
+Mutability is honored but is specific to each object in the ancestry. In other words, if the entire ancestry is immutable then no object can mutate an attribute defined in the ancestry. The same applies if the entire ancestry is mutable except, now, any child can mutate any attribute previously defined by the ancestry. Any attribute that is mutated is only mutated specific to the subclass as is standard inheritance behavior.
+
+If your ancestry is a mixed (immutable and mutable) then behavior is specific to each child in the ancestry. This means a mutable child won't make the entire ancestry mutable, only the child will be mutable. Best practice is to architect your ancestry so immutability or mutability is the same across all objects. To illustrate, here's an example with an immutable parent and mutable child:
+
+[source,ruby]
+----
+class Parent
+  include Wholeable[:one]
+
+  def initialize one: 1
+    @one = one
+  end
+end
+
+class Child < Parent
+  include Wholeable[:two, kind: :mutable]
+
+  def initialize(two: 2, **)
+    super(**)
+    @two = two
+  end
+end
+
+child = Child.new
+
+child.one = 100  # NoMethodError
+child.two = 200  # 200
+child.frozen?    # false
+----
+
+Notice, when attempting to mutate the `one` attribute, you get a `NoMethodError`. This is because `#one=` is defined by the _immutable_ parent while `#two=` is defined on the _mutable_ child.
+
+If you the flip mutability of your ancestry, you can make your parent mutable while the child immutable for different behavior. Example:
+
+[source,ruby]
+----
+class Parent
+  include Wholeable[:one, kind: :mutable]
+
+  def initialize one: 1
+    @one = one
+  end
+end
+
+class Child < Parent
+  include Wholeable[:two]
+
+  def initialize(two: 2, **)
+    super(**)
+    @two = two
+  end
+end
+
+child = Child.new
+
+child.one = 100  # FrozenError
+child.two = 200  # NoMethodError
+child.frozen?    # true
+----
+
+In this case, you get a `FrozenError` for `#one=` because the parent is _mutable_ and defined the `#one=` method but the child is _immutable_ which caused the associated attribute to be frozen. On the other hand, the `#two=` method is never defined by the subclass due to being immutable and so you you get a: `NoMethodError`.
+
+_Again, if using inheritance, ensure immutability or mutability remains consistent throughout the entire ancestry._
+
 == Caveats
 
-Whole values can be broken via the following:
+Whole values can be broken via the following situations:
 
-* *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 afterwards.
 * *Post Attributes*: Adding additional attributes after what is defined when including `Wholeable` will break your whole value object. To prevent this, let Wholeable 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 Wholeable 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.
+* *Deep Freezing*: The automatic freezing of your instances is shallow and will not deep freeze nested attributes. This behavior mimics the behavior of {data_link} objects.
+
+== Performance
+
+The performance of this gem is good but definitely slower than native support for {data_link} and {structs_link} because they are written in C. To illustrate, here's a micro benchmark for comparison:
+
+----
+INITIALIZATION
+
+ruby 3.3.5 (2024-09-03 revision ef084cc8f4) +YJIT [arm64-darwin23.6.0]
+Warming up --------------------------------------
+                Data   470.027k i/100ms
+              Struct   422.010k i/100ms
+               Whole   805.945k i/100ms
+Calculating -------------------------------------
+                Data      4.750M (± 1.1%) i/s  (210.53 ns/i) -     23.971M in   5.047225s
+              Struct      4.579M (± 1.1%) i/s  (218.38 ns/i) -     23.211M in   5.069228s
+               Whole      9.408M (± 1.2%) i/s  (106.29 ns/i) -     47.551M in   5.055033s
+
+Comparison:
+               Whole:  9407938.7 i/s - 1.60x  slower
+                Data:  4750013.8 i/s - 3.17x  slower
+              Struct:  4579253.1 i/s - 3.28x  slower
+
+BEHAVIOR
+
+ruby 3.3.5 (2024-09-03 revision ef084cc8f4) +YJIT [arm64-darwin23.6.0]
+Warming up --------------------------------------
+                Data   129.006k i/100ms
+              Struct   129.832k i/100ms
+           Wholeable    78.861k i/100ms
+Calculating -------------------------------------
+                Data      1.336M (± 3.6%) i/s  (748.33 ns/i) -      6.708M in   5.027517s
+              Struct      1.341M (± 1.7%) i/s  (745.89 ns/i) -      6.751M in   5.037050s
+           Wholeable    816.232k (± 1.9%) i/s    (1.23 μs/i) -      4.101M in   5.025751s
+
+Comparison:
+              Struct:  1340687.5 i/s
+                Data:  1336304.1 i/s - same-ish: difference falls within error
+           Wholeable:   816232.0 i/s - 1.64x  slower
+----
+
+While the above isn't bad, you can definitely see this gem is slower than Ruby's own native objects when interacting with it despite being faster upon initialization.
+
+Default to using {data_link} or {structs_link} but, if you find yourself needing a whole value object with more behavior than what a `Data` or `Struct` can provide, then this gem is a good solution.
 
 == Development
 

data/lib/wholeable/builder.rb

@@ -3,29 +3,51 @@
 module Wholeable
   # Provides core equality behavior.
   class Builder < Module
-    def initialize *keys
+    def self.add_aliases descendant
+      descendant.alias_method :deconstruct, :to_a
+      descendant.alias_method :deconstruct_keys, :to_h
+      descendant.alias_method :to_s, :inspect
+    end
+
+    def initialize *keys, kind: :immutable
       super()
       @keys = keys.uniq
-      private_methods.grep(/\A(define)_/).sort.each { |method| __send__ method }
-      freeze
+      @kind = kind
+      @members = []
+      setup
     end
 
     def included descendant
       super
+      coalesce_members descendant
 
-      descendant.class_eval <<-READER, __FILE__, __LINE__ + 1
-        def self.new(...) = super.freeze
+      descendant.class_eval <<-METHODS, __FILE__, __LINE__ + 1
+        def self.[](...) = new(...)
 
-        attr_reader #{keys.map(&:inspect).join ", "}
-      READER
+        def self.new(...) = #{mutable?} ? super.dup : super.freeze
 
-      descendant.alias_method :deconstruct, :to_a
-      descendant.alias_method :deconstruct_keys, :to_h
+        def self.members = #{members}
+
+        #{mutable? ? :attr_accessor : :attr_reader} #{keys.map(&:inspect).join ", "}
+      METHODS
+
+      self.class.add_aliases descendant
     end
 
     private
 
-    attr_reader :keys
+    attr_reader :keys, :kind, :members
+
+    def setup
+      private_methods.grep(/\A(define)_/).sort.each { |method| __send__ method }
+      freeze
+    end
+
+    def coalesce_members descendant
+      members.replace(descendant.respond_to?(:members) ? (descendant.members + keys).uniq : keys)
+    end
+
+    def mutable? = kind == :mutable
 
     def define_diff
       define_method :diff do |other|
@@ -46,34 +68,36 @@ module Wholeable
       define_method(:==) { |other| other.is_a?(self.class) && hash == other.hash }
     end
 
-    def define_hash local_keys = keys
+    def define_hash
       define_method :hash do
-        local_keys.map { |key| public_send key }
-                  .prepend(self.class)
-                  .hash
+        members.map { |key| public_send key }
+               .prepend(self.class)
+               .hash
       end
     end
 
-    def define_inspect local_keys = keys
+    def define_inspect
       define_method :inspect do
         klass = self.class
         name = klass.name || klass.inspect
 
-        local_keys.map { |key| "@#{key}=#{public_send(key).inspect}" }
-                  .join(", ")
-                  .then { |pairs| "#<#{name} #{pairs}>" }
+        members.map { |key| "@#{key}=#{public_send(key).inspect}" }
+               .join(", ")
+               .then { |pairs| "#<#{name} #{pairs}>" }
       end
     end
 
-    def define_to_a local_keys = keys
+    def define_members(local_members = members) = define_method(:members) { local_members }
+
+    def define_to_a
       define_method :to_a do
-        local_keys.reduce([]) { |array, key| array.append public_send(key) }
+        members.reduce([]) { |collection, key| collection.append public_send(key) }
       end
     end
 
-    def define_to_h local_keys = keys
+    def define_to_h
       define_method :to_h do
-        local_keys.each.with_object({}) { |key, dictionary| dictionary[key] = public_send key }
+        members.each.with_object({}) { |key, attributes| attributes[key] = public_send key }
       end
     end
 

data/lib/wholeable.rb

@@ -4,5 +4,5 @@ require "wholeable/builder"
 
 # Main namespace.
 module Wholeable
-  def self.[](*) = Builder.new(*)
+  def self.[](*, **) = Builder.new(*, **)
 end

data/wholeable.gemspec

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wholeable
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-10-04 00:00:00.000000000 Z
+date: 2024-11-09 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -80,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
+rubygems_version: 3.5.23
 signing_key:
 specification_version: 4
 summary: Provides whole value object behavior.