wholable 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42f00bcfb8063a21a4fb8f6427424078be9ce45365d2b41f5a6c053133b059d7
+  data.tar.gz: 267014e8011488d2b9e3db0fcdecebe6a70c0032e8f47ea60cb0d3b035174719
+SHA512:
+  metadata.gz: 94334fe408aa2e6ac16589688f1c3e3a4d746f738ef9ec4c75d2031e10898463ce63954e0c8f147167396a0a18da79d312a75a5a3ce52bc663a773be824841d9
+  data.tar.gz: b921837f4c80fb2651cf6a135c367c0fd2bbf18a5dfa47c0ad52838ad6f6482b90492e18d312093660f2f4ee693f56c49768647b50c8f7e0b5c93d0a9d99c9d7

data/LICENSE.adoc

@@ -0,0 +1,134 @@
+= Hippocratic License
+
+Version: 2.1.0.
+
+Purpose. The purpose of this License is for the Licensor named above to
+permit the Licensee (as defined below) broad permission, if consistent
+with Human Rights Laws and Human Rights Principles (as each is defined
+below), to use and work with the Software (as defined below) within the
+full scope of Licensor’s copyright and patent rights, if any, in the
+Software, while ensuring attribution and protecting the Licensor from
+liability.
+
+Permission and Conditions. The Licensor grants permission by this
+license ("License"), free of charge, to the extent of Licensor’s
+rights under applicable copyright and patent law, to any person or
+entity (the "Licensee") obtaining a copy of this software and
+associated documentation files (the "Software"), to do everything with
+the Software that would otherwise infringe (i) the Licensor’s copyright
+in the Software or (ii) any patent claims to the Software that the
+Licensor can license or becomes able to license, subject to all of the
+following terms and conditions:
+
+* Acceptance. This License is automatically offered to every person and
+entity subject to its terms and conditions. Licensee accepts this
+License and agrees to its terms and conditions by taking any action with
+the Software that, absent this License, would infringe any intellectual
+property right held by Licensor.
+* Notice. Licensee must ensure that everyone who gets a copy of any part
+of this Software from Licensee, with or without changes, also receives
+the License and the above copyright notice (and if included by the
+Licensor, patent, trademark and attribution notice). Licensee must cause
+any modified versions of the Software to carry prominent notices stating
+that Licensee changed the Software. For clarity, although Licensee is
+free to create modifications of the Software and distribute only the
+modified portion created by Licensee with additional or different terms,
+the portion of the Software not modified must be distributed pursuant to
+this License. If anyone notifies Licensee in writing that Licensee has
+not complied with this Notice section, Licensee can keep this License by
+taking all practical steps to comply within 30 days after the notice. If
+Licensee does not do so, Licensee’s License (and all rights licensed
+hereunder) shall end immediately.
+* Compliance with Human Rights Principles and Human Rights Laws.
+[arabic]
+. Human Rights Principles.
+[loweralpha]
+.. Licensee is advised to consult the articles of the United Nations
+Universal Declaration of Human Rights and the United Nations Global
+Compact that define recognized principles of international human rights
+(the "Human Rights Principles"). Licensee shall use the Software in a
+manner consistent with Human Rights Principles.
+.. Unless the Licensor and Licensee agree otherwise, any dispute,
+controversy, or claim arising out of or relating to (i) Section 1(a)
+regarding Human Rights Principles, including the breach of Section 1(a),
+termination of this License for breach of the Human Rights Principles,
+or invalidity of Section 1(a) or (ii) a determination of whether any Law
+is consistent or in conflict with Human Rights Principles pursuant to
+Section 2, below, shall be settled by arbitration in accordance with the
+Hague Rules on Business and Human Rights Arbitration (the "Rules");
+provided, however, that Licensee may elect not to participate in such
+arbitration, in which event this License (and all rights licensed
+hereunder) shall end immediately. The number of arbitrators shall be one
+unless the Rules require otherwise.
++
+Unless both the Licensor and Licensee agree to the contrary: (1) All
+documents and information concerning the arbitration shall be public and
+may be disclosed by any party; (2) The repository referred to under
+Article 43 of the Rules shall make available to the public in a timely
+manner all documents concerning the arbitration which are communicated
+to it, including all submissions of the parties, all evidence admitted
+into the record of the proceedings, all transcripts or other recordings
+of hearings and all orders, decisions and awards of the arbitral
+tribunal, subject only to the arbitral tribunal’s powers to take such
+measures as may be necessary to safeguard the integrity of the arbitral
+process pursuant to Articles 18, 33, 41 and 42 of the Rules; and (3)
+Article 26(6) of the Rules shall not apply.
+. Human Rights Laws. The Software shall not be used by any person or
+entity for any systems, activities, or other uses that violate any Human
+Rights Laws. "Human Rights Laws" means any applicable laws,
+regulations, or rules (collectively, "Laws") that protect human,
+civil, labor, privacy, political, environmental, security, economic, due
+process, or similar rights; provided, however, that such Laws are
+consistent and not in conflict with Human Rights Principles (a dispute
+over the consistency or a conflict between Laws and Human Rights
+Principles shall be determined by arbitration as stated above). Where
+the Human Rights Laws of more than one jurisdiction are applicable or in
+conflict with respect to the use of the Software, the Human Rights Laws
+that are most protective of the individuals or groups harmed shall
+apply.
+. Indemnity. Licensee shall hold harmless and indemnify Licensor (and
+any other contributor) against all losses, damages, liabilities,
+deficiencies, claims, actions, judgments, settlements, interest, awards,
+penalties, fines, costs, or expenses of whatever kind, including
+Licensor’s reasonable attorneys’ fees, arising out of or relating to
+Licensee’s use of the Software in violation of Human Rights Laws or
+Human Rights Principles.
+* Failure to Comply. Any failure of Licensee to act according to the
+terms and conditions of this License is both a breach of the License and
+an infringement of the intellectual property rights of the Licensor
+(subject to exceptions under Laws, e.g., fair use). In the event of a
+breach or infringement, the terms and conditions of this License may be
+enforced by Licensor under the Laws of any jurisdiction to which
+Licensee is subject. Licensee also agrees that the Licensor may enforce
+the terms and conditions of this License against Licensee through
+specific performance (or similar remedy under Laws) to the extent
+permitted by Laws. For clarity, except in the event of a breach of this
+License, infringement, or as otherwise stated in this License, Licensor
+may not terminate this License with Licensee.
+* Enforceability and Interpretation. If any term or provision of this
+License is determined to be invalid, illegal, or unenforceable by a
+court of competent jurisdiction, then such invalidity, illegality, or
+unenforceability shall not affect any other term or provision of this
+License or invalidate or render unenforceable such term or provision in
+any other jurisdiction; provided, however, subject to a court
+modification pursuant to the immediately following sentence, if any term
+or provision of this License pertaining to Human Rights Laws or Human
+Rights Principles is deemed invalid, illegal, or unenforceable against
+Licensee by a court of competent jurisdiction, all rights in the
+Software granted to Licensee shall be deemed null and void as between
+Licensor and Licensee. Upon a determination that any term or provision
+is invalid, illegal, or unenforceable, to the extent permitted by Laws,
+the court may modify this License to affect the original purpose that
+the Software be used in compliance with Human Rights Principles and
+Human Rights Laws as closely as possible. The language in this License
+shall be interpreted as to its fair meaning and not strictly for or
+against any party.
+* Disclaimer. TO THE FULL EXTENT ALLOWED BY LAW, THIS SOFTWARE COMES
+"AS IS," WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED, AND LICENSOR AND
+ANY OTHER CONTRIBUTOR SHALL NOT BE LIABLE TO ANYONE FOR ANY DAMAGES OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+OR THIS LICENSE, UNDER ANY KIND OF LEGAL CLAIM.
+
+This Hippocratic License is an link:https://ethicalsource.dev[Ethical Source license] and is offered
+for use by licensors and licensees at their own risk, on an "AS IS" basis, and with no warranties
+express or implied, to the maximum extent permitted by Laws.

data/README.adoc

@@ -0,0 +1,166 @@
+:toc: macro
+:toclevels: 5
+:figure-caption!:
+
+:data_link: link:https://alchemists.io/articles/ruby_data[Data]
+
+= 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.
+
+toc::[]
+
+== Features
+
+* Ensures equality (i.e. `#==` and `#eql?`) is determined by attribute values and not object identity (i.e. `#equal?`).
+* 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.
+
+== Requirements
+
+. link:https://www.ruby-lang.org[Ruby].
+
+== Setup
+
+To install _with_ security, run:
+
+[source,bash]
+----
+# 💡 Skip this line if you already have the public certificate installed.
+gem cert --add <(curl --compressed --location https://alchemists.io/projects/wholable/gems.pem)
+gem install wholable --trust-policy HighSecurity
+----
+
+To install _without_ security, run:
+
+[source,bash]
+----
+gem install wholable
+----
+
+You can also add the gem directly to your project:
+
+[source,bash]
+----
+bundle add wholable
+----
+
+Once the gem is installed, you only need to require it:
+
+[source,ruby]
+----
+require "wholable"
+----
+
+== Usage
+
+To use, include Wholable along with a list of attributes that make up your whole value object:
+
+[source,ruby]
+----
+class Person
+  include Wholable[:name, :email]
+
+  def initialize name:, email:
+    @name = name
+    @email = email
+  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.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.name             # "Jill Smith"
+jill.email            # "jill@example.com"
+
+jill == jill          # true
+jill == jill_two      # true
+jill == jack          # false
+
+jill.eql? jill        # true
+jill.eql? jill_two    # true
+jill.eql? jack        # false
+
+jill.equal? jill      # true
+jill.equal? jill_two  # false
+jill.equal? jack      # false
+
+jill.hash             # 3650965837788801745
+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:
+
+. 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.
+
+== Caveats
+
+The whole value contract created for you when using this gem can be broken by doing 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.
+* *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. 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.
+
+== Development
+
+To contribute, run:
+
+[source,bash]
+----
+git clone https://github.com/bkuhlmann/wholable
+cd wholable
+bin/setup
+----
+
+You can also use the IRB console for direct access to all objects:
+
+[source,bash]
+----
+bin/console
+----
+
+== Tests
+
+To test, run:
+
+[source,bash]
+----
+bin/rake
+----
+
+== link:https://alchemists.io/policies/license[License]
+
+== link:https://alchemists.io/policies/security[Security]
+
+== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]
+
+== link:https://alchemists.io/policies/contributions[Contributions]
+
+== link:https://alchemists.io/projects/wholable/versions[Versions]
+
+== link:https://alchemists.io/community[Community]
+
+== Credits
+
+* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].
+* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

data/lib/wholable/comparable.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Wholable
+  # Provides object equality comparison methods.
+  module Comparable
+    def eql?(other) = instance_of?(other.class) && hash == other.hash
+
+    def ==(other) = other.is_a?(self.class) && hash == other.hash
+  end
+end

data/lib/wholable/equatable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Wholable
+  # Provides core equality behavior.
+  class Equatable < Module
+    def initialize *keys
+      super()
+      @keys = keys.uniq
+      define_hash
+      define_inspect
+      freeze
+    end
+
+    def included descendant
+      super
+      define_readers descendant
+      descendant.include Comparable
+      descendant.prepend Freezable
+    end
+
+    private
+
+    attr_reader :keys
+
+    def define_readers descendant
+      descendant.class_eval <<-READERS, __FILE__, __LINE__ + 1
+        attr_reader #{keys.map(&:inspect).join ", "}
+      READERS
+    end
+
+    def define_hash
+      local_keys = keys
+
+      define_method :hash do
+        local_keys.map { |key| public_send key }
+                  .prepend(self.class)
+                  .hash
+      end
+    end
+
+    # :reek:TooManyStatements
+    def define_inspect
+      local_keys = keys
+
+      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}>" }
+      end
+    end
+  end
+end

data/lib/wholable/freezable.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Wholable
+  # Ensures an object is frozen after being initialized.
+  module Freezable
+    def initialize(...)
+      super(...)
+      freeze
+    end
+  end
+end

data/lib/wholable.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "wholable/comparable"
+require "wholable/equatable"
+require "wholable/freezable"
+
+# Main namespace.
+module Wholable
+  def self.[](...) = Equatable.new(...)
+end

data/wholable.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = "wholable"
+  spec.version = "0.0.0"
+  spec.authors = ["Brooke Kuhlmann"]
+  spec.email = ["brooke@alchemists.io"]
+  spec.homepage = "https://alchemists.io/projects/wholable"
+  spec.summary = "A whole value object mixin."
+  spec.license = "Hippocratic-2.1"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/bkuhlmann/wholable/issues",
+    "changelog_uri" => "https://alchemists.io/projects/wholable/versions",
+    "documentation_uri" => "https://alchemists.io/projects/wholable",
+    "funding_uri" => "https://github.com/sponsors/bkuhlmann",
+    "label" => "Wholable",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => "https://github.com/bkuhlmann/wholable"
+  }
+
+  spec.signing_key = Gem.default_key_path
+  spec.cert_chain = [Gem.default_cert_path]
+
+  spec.required_ruby_version = "~> 3.2"
+
+  spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
+  spec.files = Dir["*.gemspec", "lib/**/*"]
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: wholable
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Brooke Kuhlmann
+autorequire:
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIEeDCCAuCgAwIBAgIBATANBgkqhkiG9w0BAQsFADBBMQ8wDQYDVQQDDAZicm9v
+  a2UxGjAYBgoJkiaJk/IsZAEZFgphbGNoZW1pc3RzMRIwEAYKCZImiZPyLGQBGRYC
+  aW8wHhcNMjMwMzIyMTYxNDQxWhcNMjUwMzIxMTYxNDQxWjBBMQ8wDQYDVQQDDAZi
+  cm9va2UxGjAYBgoJkiaJk/IsZAEZFgphbGNoZW1pc3RzMRIwEAYKCZImiZPyLGQB
+  GRYCaW8wggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQCro8tj5/E1Hg88
+  f4qfiwPVd2zJQHvdYt4GHVvuHRRgx4HGhJuNp+4BId08RBn7V6V1MW6MY3kezRBs
+  M+7QOQ4b1xNLTvY7FYQB1wGK5a4x7TTokDrPYQxDB2jmsdDYCzVbIMrAvUfcecRi
+  khyGZCdByiiCl4fKv77P12tTT+NfsvXkLt/AYCGwjOUyGKTQ01Z6eC09T27GayPH
+  QQvIkakyFgcJtzSyGzs8bzK5q9u7wQ12MNTjJoXzW69lqp0oNvDylu81EiSUb5S6
+  QzzPxZBiRB1sgtbt1gUbVI262ZDq1gR+HxPFmp+Cgt7ZLIJZAtesQvtcMzseXpfn
+  hpmm0Sw22KGhRAy/mqHBRhDl5HqS1SJp2Ko3lcnpXeFResp0HNlt8NSu13vhC08j
+  GUHU9MyIXbFOsnp3K3ADrAVjPWop8EZkmUR3MV/CUm00w2cZHCSGiXl1KMpiVKvk
+  Ywr1gd2ZME4QLSo+EXUtLxDUa/W3xnBS8dBOuMMz02FPWYr3PN8CAwEAAaN7MHkw
+  CQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0OBBYEFAFgmv0tYMZnItuPycSM
+  F5wykJEVMB8GA1UdEQQYMBaBFGJyb29rZUBhbGNoZW1pc3RzLmlvMB8GA1UdEgQY
+  MBaBFGJyb29rZUBhbGNoZW1pc3RzLmlvMA0GCSqGSIb3DQEBCwUAA4IBgQAX+EGY
+  9RLYGxF1VLZz+G1ACQc4uyrCB6kXwI06kzUa5dF9tPXqTX9ffnz3/W8ck2IQhKzu
+  MKO2FVijzbDWTsZeZGglS4E+4Jxpau1lU9HhOIcKolv6LeC6UdALTFudY+GLb8Xw
+  REXgaJkjzzhkUSILmEnRwEbY08dVSl7ZAaxVI679vfI2yapLlIwpbBgmQTiTvPr3
+  qyyLUno9flYEOv9fmGHunSrM+gE0/0niGTXa5GgXBXYGS2he4LQGgSBfGp/cTwMU
+  rDKJRcusZ12lNBeDfgqACz/BBJF8FLodgk6rGMRZz7+ZmjjHEmpG5bQpR6Q2BuWL
+  XMtYk/QzaWuhiR7pWjiF8jbdd7RO6or0ohq7iFkokz/5xrtQ/vPzU2RQ3Qc6YaKw
+  3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
+  gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
+  -----END CERTIFICATE-----
+date: 2023-07-27 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- brooke@alchemists.io
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.adoc
+- LICENSE.adoc
+files:
+- LICENSE.adoc
+- README.adoc
+- lib/wholable.rb
+- lib/wholable/comparable.rb
+- lib/wholable/equatable.rb
+- lib/wholable/freezable.rb
+- wholable.gemspec
+homepage: https://alchemists.io/projects/wholable
+licenses:
+- Hippocratic-2.1
+metadata:
+  bug_tracker_uri: https://github.com/bkuhlmann/wholable/issues
+  changelog_uri: https://alchemists.io/projects/wholable/versions
+  documentation_uri: https://alchemists.io/projects/wholable
+  funding_uri: https://github.com/sponsors/bkuhlmann
+  label: Wholable
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/bkuhlmann/wholable
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.17
+signing_key:
+specification_version: 4
+summary: A whole value object mixin.
+test_files: []