value_semantics 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9917cde0bb66e10e931d39308a1d968973e10f5de4b60b15898cb3d390f77fb9
-  data.tar.gz: b9ab7670cc254252d357a8276c1fb98305e9c3e60634354883e078179bad7b03
+  metadata.gz: e86c0e4467ff36d89870545718de723b0a0b62ff21dc50d30a3f6e1c0766c4c1
+  data.tar.gz: '011313548dfe90ee7b686bc91338b5e0f403ce2dd26f98fd607fdf16ef2c5ce7'
 SHA512:
-  metadata.gz: 40c1a0ef2a51f2e18465013660a71ca3dbd50fd615dd1e0e7dd4e6e0a65ba3fc5f742132b62467178dad75f5e14452d8ebc38742fa8928254baad8709e89dfd6
-  data.tar.gz: 9d1eebc8605d6aed14be4eb0fec9fb78f7eca69894e3ee3d79c34a8c41763542b4a8ffc8fd57eba2848735b0732286d8cacbb46a64d509c5fe89a519c06afbe3
+  metadata.gz: ecd428749dd01e806df9bbd4a361084f1b066298d464fea3a04ff7f66214ba224b99b93c7902f513c1c4f89fc52690779f4a14bb2c7e78106a212456a8f2c14d
+  data.tar.gz: 86c31d6565594493891581dde7feac4f9a9a5c1ff39b86874fd1be74d6bf3827b9a3311369dcaf9a76d9c41ca03be9abc464736ac86d09d316125e9472534554

data/CHANGELOG.md

@@ -5,6 +5,23 @@ Notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.4.0] - 2020-08-01
+### Added
+- Value objects can be instantiated from any object that responds to `#to_h`.
+  Previously attributes were required to be given as a `Hash`.
+
+- Added monkey patching for super-convenient attribute definitions. This is
+  **not** available by default, and needs to be explicitly enabled with
+  `ValueSemantics.monkey_patch!` or `require 'value_semantics/monkey_patched'`.
+
+### Changed
+- Improved exception messages for easier development experience
+
+- Raises `ValueSemantics::InvalidValue` instead of `ArgumentError` when
+  attempting to initialize with an invalid value. `ValueSemantics::InvalidValue`
+  is a subclass of `ArgumentError`, so this change should be backward
+  compatible.
+
 ## [3.3.0] - 2020-07-17
 ### Added
 - Added support for pattern matching in Ruby 2.7

data/README.md

@@ -15,10 +15,15 @@ These are intended for internal use, as opposed to validating user input like Ac
 Invalid or missing attributes cause an exception for developers,
 not an error message intended for application users.
 
-See the [announcement blog post][] for some of the rationale behind the gem, and some [discussion on Reddit].
+See:
 
-[announcement blog post]: https://www.rubypigeon.com/posts/value-semantics-gem-for-making-value-classes/
-[discussion on Reddit]: https://www.reddit.com/r/ruby/comments/akz4fs/valuesemanticsa_gem_for_making_value_classes/
+ - The [announcement blog post][blog post] for some of the rationale behind the gem
+ - [RubyTapas episode #584][rubytapas] for an example usage scenario
+ - Some [discussion on Reddit][reddit]
+
+[blog post]: https://www.rubypigeon.com/posts/value-semantics-gem-for-making-value-classes/
+[rubytapas]: https://www.rubytapas.com/2019/07/09/from-hash-to-value-object/
+[reddit]: https://www.reddit.com/r/ruby/comments/akz4fs/valuesemanticsa_gem_for_making_value_classes/
 
 
 Defining and Creating Value Objects
@@ -50,9 +55,13 @@ Person.new(birthday: nil)
 #=> #<Person name="Anon Emous" birthday=nil>
 ```
 
-The curly bracket syntax used with `ValueSemantics.for_attributes` is, unfortunately,
-mandatory due to Ruby's precedence rules.
-The `do`/`end` syntax will not work unless you surround the whole thing with parenthesis.
+Value objects are typically initialized with keyword arguments or a `Hash`, but
+will accept any object that responds to `#to_h`.
+
+The curly bracket syntax used with `ValueSemantics.for_attributes` is,
+unfortunately, mandatory due to Ruby's precedence rules. For a shorter
+alternative method that works better with `do`/`end`, see [Convenience (Monkey
+Patch)](#convenience-monkey-patch) below.
 
 
 Using Value Objects
@@ -71,48 +80,71 @@ end
 tom = Person.new(name: 'Tom')
 
 
-#
 # Read-only attributes
-#
 tom.name  #=> "Tom"
 tom.age  #=> 31
 
 
-#
 # Convert to Hash
-#
 tom.to_h  #=> { :name => "Tom", :age => 31 }
 
 
-#
 # Non-destructive updates
-#
 old_tom = tom.with(age: 99)
-
 old_tom  #=> #<Person name="Tom" age=99>
 tom      #=> #<Person name="Tom" age=31> (unchanged)
 
 
-#
 # Equality
-#
 other_tom = Person.new(name: 'Tom', age: 31)
-
 tom == other_tom  #=> true
 tom.eql?(other_tom)  #=> true
 tom.hash == other_tom.hash  #=> true
 
 
-#
 # Ruby 2.7+ pattern matching
-#
 case tom
-in { name: "Tom", age: }
+in name: "Tom", age:
   puts age  # outputs: 31
 end
 ```
 
 
+Convenience (Monkey Patch)
+--------------------------
+
+There is a shorter way to define value attributes:
+
+```ruby
+  class Person
+    value_semantics do
+      name String
+      age Integer
+    end
+  end
+```
+
+**This is disabled by default**, to avoid polluting every class with an extra
+class method.
+
+This convenience method can be enabled in two ways:
+
+ 1. Add a `require:` option to your `Gemfile` like this:
+
+    ```ruby
+    gem 'value_semantics', '~> 3.3', require: 'value_semantics/monkey_patched'
+    ```
+
+ 2. Alternatively, you can call `ValueSemantics.monkey_patch!` somewhere early
+    in the boot sequence of your code -- at the top of your script, for example,
+    or `config/boot.rb` if it's a Rails project.
+
+    ```ruby
+    require 'value_semantics'
+    ValueSemantics.monkey_patch!
+    ```
+
+
 Defaults
 --------
 
@@ -159,13 +191,13 @@ end
 
 Person.new(name: 'Tom', ...)  # works
 Person.new(name: 5, ...)
-#=> ArgumentError:
-#=>     Value for attribute 'name' is not valid: 5
+#=> ValueSemantics::InvalidValue:
+#=>     Attribute `Person#name` is invalid: 5
 
 Person.new(birthday: "1970-01-01", ...)  # works
 Person.new(birthday: "hello", ...)
-#=> ArgumentError:
-#=>     Value for attribute 'birthday' is not valid: "hello"
+#=> ValueSemantics::InvalidValue:
+#=>     Attribute 'Person#birthday' is invalid: "hello"
 ```
 
 
@@ -220,8 +252,8 @@ end
 
 Person.new(age: 9)  # works
 Person.new(age: 8)
-#=> ArgumentError:
-#=>     Value for attribute 'age' is not valid: 8
+#=> ValueSemantics::InvalidValue:
+#=>     Attribute 'Person#age' is invalid: 8
 ```
 
 Default attribute values also pass through validation.
@@ -233,46 +265,48 @@ Coercion
 Coercion allows non-standard or "convenience" values to be converted into
 proper, valid values, where possible.
 
-For example, an object with an `IPAddr` attribute may allow string values,
-which are then coerced into `IPAddr` objects.
+For example, an object with an `Pathname` attribute may allow string values,
+which are then coerced into `Pathname` objects.
 
 Using the option `coerce: true`,
 coercion happens through a custom class method called `coerce_#{attr}`,
 which takes the raw value as an argument, and returns the coerced value.
 
 ```ruby
-class Server
+require 'pathname'
+
+class Document
   include ValueSemantics.for_attributes {
-    address IPAddr, coerce: true
+    path Pathname, coerce: true
   }
 
-  def self.coerce_address(value)
+  def self.coerce_path(value)
     if value.is_a?(String)
-      IPAddr.new(value)
+      Pathname.new(value)
     else
       value
     end
   end
 end
 
-Server.new(address: '127.0.0.1')
-#=> #<Server address=#<IPAddr: IPv4:127.0.0.1/255.255.255.255>>
+Document.new(path: '~/Documents/whatever.doc')
+#=> #<Document path=#<Pathname:~/Documents/whatever.doc>>
 
-Server.new(address: IPAddr.new('127.0.0.1'))
-#=> #<Server address=#<IPAddr: IPv4:127.0.0.1/255.255.255.255>>
+Document.new(path: Pathname.new('~/Documents/whatever.doc'))
+#=> #<Document path=#<Pathname:~/Documents/whatever.doc>>
 
-Server.new(address: 42)
-#=> ArgumentError:
-#=>     Value for attribute 'address' is not valid: 42
+Document.new(path: 42)
+#=> ValueSemantics::InvalidValue:
+#=>     Attribute 'Document#path' is invalid: 42
 ```
 
 You can also use any callable object as a coercer.
 That means, you could use a lambda:
 
 ```ruby
-class Server
+class Document
   include ValueSemantics.for_attributes {
-    address IPAddr, coerce: ->(value) { IPAddr.new(value) }
+    path Pathname, coerce: ->(value) { Pathname.new(value) }
   }
 end
 ```
@@ -280,25 +314,25 @@ end
 Or a custom class:
 
 ```ruby
-class MyAddressCoercer
+class MyPathCoercer
   def call(value)
-    IPAddr.new(value)
+    Pathname.new(value)
   end
 end
 
-class Server
+class Document
   include ValueSemantics.for_attributes {
-    address IPAddr, coerce: MyAddressCoercer.new
+    path Pathname, coerce: MyPathCoercer.new
   }
 end
 ```
 
-Or reuse an existing class method:
+Or reuse an existing method:
 
 ```ruby
-class Server
+class Document
   include ValueSemantics.for_attributes {
-    address IPAddr, coerce: IPAddr.method(:new)
+    path Pathname, coerce: Pathname.method(:new)
   }
 end
 ```
@@ -310,7 +344,7 @@ Another option is to raise an error within the coercion method.
 
 Default attribute values also pass through coercion.
 For example, the default value could be a string,
-which would then be coerced into an `IPAddr` object.
+which would then be coerced into an `Pathname` object.
 
 
 ## ValueSemantics::Struct
@@ -350,7 +384,15 @@ Or install it yourself as:
 Bug reports and pull requests are welcome on GitHub at:
 https://github.com/tomdalling/value_semantics
 
-Keep in mind that this gem aims to be as close to 100% backwards compatible as possible.
+Keep in mind that this gem aims to be as close to 100% backwards compatible as
+possible.
+
+I'm happy to accept PRs that:
+
+ - Improve error messages for a better developer experience, especially those
+   that support a TDD workflow.
+ - Add new, helpful validators
+ - Implement automatic freezing of value objects (must be opt-in)
 
 ## License
 

data/lib/value_semantics.rb

@@ -3,6 +3,7 @@ module ValueSemantics
   class UnrecognizedAttributes < Error; end
   class NoDefaultValue < Error; end
   class MissingAttributes < Error; end
+  class InvalidValue < ArgumentError; end
 
   NOT_SPECIFIED = Object.new.freeze
 
@@ -43,6 +44,39 @@ module ValueSemantics
     end
   end
 
+  #
+  # Makes the `.value_semantics` convenience method available to all classes
+  #
+  # `.value_semantics` is a shortcut for `include ValueSemantics.for_attributes`.
+  # Instead of:
+  #
+  #     class Person
+  #       include ValueSemantics.for_attributes {
+  #         name String
+  #       }
+  #     end
+  #
+  # You can just write:
+  #
+  #     class Person
+  #       value_semantics do
+  #         name String
+  #       end
+  #     end
+  #
+  # Alternatively, you can `require 'value_semantics/monkey_patched'`, which
+  # will call this method automatically.
+  #
+  def self.monkey_patch!
+    Class.class_eval do
+      # @!visibility private
+      def value_semantics(&block)
+        include ValueSemantics.for_attributes(&block)
+      end
+      private :value_semantics
+    end
+  end
+
   #
   # All the class methods available on ValueSemantics classes
   #
@@ -55,6 +89,11 @@ module ValueSemantics
     #                  was included into this class.
     #
     def value_semantics
+      if block_given?
+        # caller is trying to use the monkey-patched Class method
+        raise "`#{self}` has already included ValueSemantics"
+      end
+
       self::VALUE_SEMANTICS_RECIPE__
     end
   end
@@ -64,15 +103,31 @@ module ValueSemantics
   #
   module InstanceMethods
     #
-    # Creates a value object based on a Hash of attributes
+    # Creates a value object based on a hash of attributes
     #
-    # @param given_attrs [Hash] a hash of attributes, with symbols for keys
-    # @raise [UnrecognizedAttributes] if given_attrs contains keys that are not attributes
-    # @raise [MissingAttributes] if given_attrs is missing any attributes that do not have defaults
-    # @raise [ArgumentError] if any attribute values do no pass their validators
+    # @param attributes [#to_h] A hash of attribute values by name. Typically a
+    #   `Hash`, but can be any object that responds to `#to_h`.
     #
-    def initialize(given_attrs = {})
-      remaining_attrs = given_attrs.dup
+    # @raise [UnrecognizedAttributes] if given_attrs contains keys that are not
+    #   attributes
+    # @raise [MissingAttributes] if given_attrs is missing any attributes that
+    #   do not have defaults
+    # @raise [InvalidValue] if any attribute values do no pass their validators
+    # @raise [TypeError] if the argument does not respond to `#to_h`
+    #
+    def initialize(attributes = nil)
+      attributes_hash =
+        if attributes.respond_to?(:to_h)
+          attributes.to_h
+        else
+          raise TypeError, <<-END_MESSAGE.strip.gsub(/\s+/, ' ')
+            Can not initialize a `#{self.class}` with a `#{attributes.class}`
+            object. This argument is typically a `Hash` of attributes, but can
+            be any object that responds to `#to_h`.
+          END_MESSAGE
+        end
+
+      remaining_attrs = attributes_hash.dup
 
       self.class.value_semantics.attributes.each do |attr|
         key, value = attr.determine_from!(remaining_attrs, self.class)
@@ -81,8 +136,14 @@ module ValueSemantics
       end
 
       unless remaining_attrs.empty?
-        unrecognised = remaining_attrs.keys.map(&:inspect).join(', ')
-        raise UnrecognizedAttributes, "Unrecognized attributes: #{unrecognised}"
+        raise(
+          UnrecognizedAttributes,
+          "`#{self.class}` does not define attributes: " +
+            remaining_attrs
+              .keys
+              .map { |k| '`' + k.inspect + '`' }
+              .join(', ')
+        )
       end
     end
 
@@ -183,7 +244,7 @@ module ValueSemantics
                     coerce: nil)
       generator = begin
         if default_generator && !default.equal?(NOT_SPECIFIED)
-          raise ArgumentError, "Attribute '#{name}' can not have both a :default and a :default_generator"
+          raise ArgumentError, "Attribute `#{name}` can not have both a `:default` and a `:default_generator`"
         elsif default_generator
           default_generator
         elsif !default.equal?(NOT_SPECIFIED)
@@ -204,7 +265,7 @@ module ValueSemantics
     def determine_from!(attr_hash, klass)
       raw_value = attr_hash.fetch(name) do
         if default_generator.equal?(NO_DEFAULT_GENERATOR)
-          raise MissingAttributes, "Value missing for attribute '#{name}'"
+          raise MissingAttributes, "Attribute `#{klass}\##{name}` has no value"
         else
           default_generator.call
         end
@@ -215,7 +276,7 @@ module ValueSemantics
       if validate?(coerced_value)
         [name, coerced_value]
       else
-        raise ArgumentError, "Value for attribute '#{name}' is not valid: #{coerced_value.inspect}"
+        raise InvalidValue, "Attribute `#{klass}\##{name}` is invalid: #{coerced_value.inspect}"
       end
     end
 

data/lib/value_semantics/monkey_patched.rb

@@ -0,0 +1,3 @@
+require 'value_semantics'
+
+ValueSemantics.monkey_patch!

data/lib/value_semantics/version.rb

@@ -1,3 +1,3 @@
 module ValueSemantics
-  VERSION = "3.3.0"
+  VERSION = "3.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: value_semantics
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Tom Dalling
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-17 00:00:00.000000000 Z
+date: 2020-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: super_diff
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mutant-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +121,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/value_semantics.rb
+- lib/value_semantics/monkey_patched.rb
 - lib/value_semantics/version.rb
 homepage: https://github.com/tomdalling/value_semantics
 licenses:
@@ -114,7 +129,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/tomdalling/value_semantics/issues
   changelog_uri: https://github.com/tomdalling/value_semantics/blob/master/CHANGELOG.md
-  documentation_uri: https://github.com/tomdalling/value_semantics/blob/v3.3.0/README.md
+  documentation_uri: https://github.com/tomdalling/value_semantics/blob/v3.4.0/README.md
   source_code_uri: https://github.com/tomdalling/value_semantics
 post_install_message: 
 rdoc_options: []
@@ -131,8 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: Makes value classes, with lightweight validation and coercion.