value_semantics 3.1.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4ff5d3aeb6f4aed20276acec36dd859f5fc1e7e8836d3d5414208d70ef9216f
-  data.tar.gz: bb73f5257fcd66d69029cbaf080e52a53d8dd5e3101e540bb0eb48be5891ede7
+  metadata.gz: '069ef7cc15f7d9b6eae3af432d486595bfa3f89c0f68ce68ab3eda2fb5d5f9f4'
+  data.tar.gz: f8d1839f7176743cb9d7a144d5452f999048a03a5d1d86d8b86b81b648a7bfd3
 SHA512:
-  metadata.gz: 4d8db67bb3b5c5c083a0d7f8a42ce1ff0419409b44c8c45feb15865d4853253401a252fd9f550e320db5e4eda62993d3527088a094682dfcf1a7125e0d518552
-  data.tar.gz: ea6e43b825c9e5d17f63a050122435fce3e98c8fc3f488a088f8df1f70e91abe6b24c08e676caec9dbb82a4ae14fc0f326135ac647254052b83de6772f820d56
+  metadata.gz: cea465484d60d6343815072b4e81639e399b20ce528a12ce643be39e3a06051fdaddb4c58037ffac5237f7c62b823b49d888bc8d6fed925b181515751b4cfb46
+  data.tar.gz: 553a990a508956e7a2b6f96ea2ac65ee97737bc6ea5da1ea337f9d0d06b294aa61fb3e10ef1d8ce6ac5fff826b3f1bdbf17b9e805ac38b933308152929335efd

data/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.5.0] - 2020-08-17
+### Added
+- Square bracket attr reader like `person[:name]`
+- `HashOf` built-in validator, similar to `ArrayOf`
+- `.coercer` class method, to help when composing value objects
+- `ArrayCoercer` DSL method, to help when composing value objects
+
+## [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
+
+## [3.2.1] - 2020-07-11
+### Fixed
+- Fix warnings new to Ruby 2.7 about keyword arguments
+
+## [3.2.0] - 2019-09-30
+### Added
+- `ValueSemantics::Struct`, a convenience for creating a new class and mixing
+  in ValueSemantics in a single step.
+
 ## [3.1.0] - 2019-06-30
 ### Added
 - Built-in PP support for value classes

data/README.md

@@ -1,6 +1,6 @@
 [![Gem Version](https://badge.fury.io/rb/value_semantics.svg)](https://badge.fury.io/rb/value_semantics)
 [![Build Status](https://travis-ci.org/tomdalling/value_semantics.svg?branch=master)](https://travis-ci.org/tomdalling/value_semantics)
-![Mutation Coverage](https://img.shields.io/badge/mutation%20coverage-100%25-brightgreen.svg)
+![Mutation Coverage](https://img.shields.io/badge/mutation%20coverage-to%20the%20MAX-brightgreen.svg)
 
 ValueSemantics
 ==============
@@ -15,10 +15,16 @@ 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
+ - The [API documentation](https://rubydoc.info/gems/value_semantics)
+ - 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
@@ -44,15 +50,19 @@ Person.new(name: "Tom", birthday: "2020-12-25")
 #=> #<Person name="Tom" birthday=#<Date: 2020-12-25 ((2459209j,0s,0n),+0s,2299161j)>>
 
 Person.new(birthday: Date.today)
-#=> #<Person name="Anon Emous" birthday=#<Date: 2018-09-04 ((2458366j,0s,0n),+0s,2299161j)>>
+#=> #<Person name="Anon Emous" birthday=#<Date: 2020-08-04 ((2459066j,0s,0n),+0s,2299161j)>>
 
 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,39 +81,69 @@ end
 tom = Person.new(name: 'Tom')
 
 
-#
 # Read-only attributes
-#
-tom.name  #=> "Tom"
-tom.age  #=> 31
-
+tom.name    #=> "Tom"
+tom[:name]  #=> "Tom"
 
-#
 # Convert to Hash
-#
-tom.to_h  #=> { :name => "Tom", :age => 31 }
+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)
-
+tom.with(age: 99) #=> #<Person name="Tom" age=99>
+tom # (unchanged) #=> #<Person name="Tom" age=31>
 
-#
 # 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:
+  puts age
+end
+# outputs: 31
 ```
 
 
+Convenience (Monkey Patch)
+--------------------------
+
+There is a shorter way to define value attributes:
+
+```ruby
+  require 'value_semantics/monkey_patched'
+
+  class Monkey
+    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
 --------
 
@@ -119,7 +159,7 @@ class Cat
 end
 
 Cat.new
-#=> #<Cat paws=4 born_at=2018-12-21 18:42:01 +1100>
+#=> #<Cat paws=4 born_at=2020-08-04 00:16:35.15632 +1000>
 ```
 
 The `default` option is a single value.
@@ -148,15 +188,13 @@ class Person
   }
 end
 
-Person.new(name: 'Tom', ...)  # works
-Person.new(name: 5, ...)
-#=> ArgumentError:
-#=>     Value for attribute 'name' is not valid: 5
+Person.new(name: 'Tom', birthday: '2000-01-01')  # works
+Person.new(name: 5,     birthday: '2000-01-01')
+#=> !!! 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"
+Person.new(name: 'Tom', birthday: "1970-01-01")  # works
+Person.new(name: 'Tom', birthday: "hello")
+#=> !!! ValueSemantics::InvalidValue: Attribute `Person#birthday` is invalid: "hello"
 ```
 
 
@@ -168,13 +206,15 @@ for common situations:
 ```ruby
 class LightSwitch
   include ValueSemantics.for_attributes {
-
     # Bool: only allows `true` or `false`
     on? Bool()
 
     # ArrayOf: validates elements in an array
     light_ids ArrayOf(Integer)
 
+    # HashOf: validates keys/values of a homogeneous hash
+    toggle_stats HashOf(Symbol => Integer)
+
     # Either: value must match at least one of a list of validators
     color Either(Integer, String, nil)
 
@@ -186,9 +226,11 @@ end
 LightSwitch.new(
   on?: true,
   light_ids: [11, 12, 13],
+  toggle_stats: { day: 42, night: 69 },
   color: "#FFAABB",
   wierd_attr: [true, false, true, true],
 )
+#=> #<LightSwitch on?=true light_ids=[11, 12, 13] toggle_stats={:day=>42, :night=>69} color="#FFAABB" wierd_attr=[true, false, true, true]>
 ```
 
 
@@ -197,22 +239,25 @@ LightSwitch.new(
 A custom validator might look something like this:
 
 ```ruby
-module Odd
+module DottedQuad
   def self.===(value)
-    value.odd?
+    value.split('.').all? do |part|
+      ('0'..'255').cover?(part)
+    end
   end
 end
 
-class Person
+class Server
   include ValueSemantics.for_attributes {
-    age Odd
+    address DottedQuad
   }
 end
 
-Person.new(age: 9)  # works
-Person.new(age: 8)
-#=> ArgumentError:
-#=>     Value for attribute 'age' is not valid: 8
+Server.new(address: '127.0.0.1')
+#=> #<Server address="127.0.0.1">
+
+Server.new(address: '127.0.0.999')
+#=> !!! ValueSemantics::InvalidValue: Attribute `Server#address` is invalid: "127.0.0.999"
 ```
 
 Default attribute values also pass through validation.
@@ -224,46 +269,47 @@ 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
 ```
@@ -271,25 +317,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
 ```
@@ -301,7 +347,96 @@ 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.
+
+
+## Nesting
+
+It is fairly common to nest value objects inside each other. This
+works as expected, but coercion is not automatic. For nested coercion,
+use the `.coercer` class method and `ArrayCoercer` DSL method that
+ValueSemantics provides.
+
+```ruby
+class CrabClaw
+  include ValueSemantics.for_attributes {
+    size Either(:big, :small)
+  }
+end
+
+class Crab
+  include ValueSemantics.for_attributes {
+    left_claw CrabClaw, coerce: CrabClaw.coercer
+    right_claw CrabClaw, coerce: CrabClaw.coercer
+  }
+end
+
+class Ocean
+  include ValueSemantics.for_attributes {
+    crabs ArrayOf(Crab), coerce: ArrayCoercer(Crab.coercer)
+  }
+end
+
+ocean = Ocean.new(
+  crabs: [
+    {
+      left_claw: { size: :small },
+      right_claw: { size: :small },
+    }, {
+      left_claw: { size: :big },
+      right_claw: { size: :big },
+    }
+  ]
+)
+
+ocean.crabs.first #=> #<Crab left_claw=#<CrabClaw size=:small> right_claw=#<CrabClaw size=:small>>
+ocean.crabs.first.right_claw.size #=> :small
+```
+
+
+## ValueSemantics::Struct
+
+This is a convenience for making a new class and including ValueSemantics in
+one step, similar to how `Struct` works from the Ruby standard library. For
+example:
+
+```ruby
+Pigeon = ValueSemantics::Struct.new do
+  name String, default: "Jannie"
+end
+
+Pigeon.new.name #=> "Jannie"
+```
+
+
+## Known Issues
+
+Some valid attribute names result in invalid Ruby syntax when using the DSL.
+In these situations, you can use the DSL method `def_attr` instead.
+
+For example, if you want an attribute named `then`:
+
+```ruby
+# Can't do this:
+class Conditional
+  include ValueSemantics.for_attributes {
+    then String
+    else String
+  }
+end
+#=> !!! SyntaxError: README.md:375: syntax error, unexpected `then'
+#=*         then String
+#=*         ^~~~
+
+
+# This will work
+class Conditional
+  include ValueSemantics.for_attributes {
+    def_attr :then, String
+    def_attr :else, String
+  }
+end
+```
 
 
 ## Installation
@@ -326,7 +461,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,38 @@ module ValueSemantics
     end
   end
 
+  #
+  # Makes the +.value_semantics+ convenience method available to all classes
+  #
+  # +.value_semantics+ is a shortcut for {.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,8 +88,33 @@ 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
+
+    #
+    # A coercer object for the value class
+    #
+    # This is mostly useful when nesting value objects inside each other.
+    #
+    # The coercer will coerce hashes into an instance of the value class, using
+    # the hash for attribute values. It will return non-hash values unchanged.
+    #
+    # @return [#call] A callable object that can be used as a coercer
+    #
+    def coercer
+      ->(obj) do
+        if Hash === obj
+          new(obj)
+        else
+          obj
+        end
+      end
+    end
   end
 
   #
@@ -64,15 +122,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 attributes [#to_h] A hash of attribute values by name. Typically a
+    #   +Hash+, but can be any object that responds to +#to_h+.
     #
-    # @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
+    # @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(given_attrs = {})
-      remaining_attrs = given_attrs.dup
+    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 +155,34 @@ 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
+
+    #
+    # Returns the value for the given attribute name
+    #
+    # @param attr_name [Symbol] The name of the attribute. Can not be a +String+.
+    # @return The value of the attribute
+    #
+    # @raise [UnrecognizedAttributes] if the attribute does not exist
+    #
+    def [](attr_name)
+      attr = self.class.value_semantics.attributes.find do |attr|
+        attr.name.equal?(attr_name)
+      end
+
+      if attr
+        public_send(attr_name)
+      else
+        raise UnrecognizedAttributes, "`#{self.class}` has no attribute named `#{attr_name.inspect}`"
       end
     end
 
@@ -149,6 +249,10 @@ module ValueSemantics
         end
       end
     end
+
+    def deconstruct_keys(_)
+      to_h
+    end
   end
 
   #
@@ -179,7 +283,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)
@@ -200,7 +304,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
@@ -211,7 +315,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
 
@@ -242,6 +346,8 @@ module ValueSemantics
   # Contains all the configuration necessary to bake a ValueSemantics module
   #
   # @see ValueSemantics.bake_module
+  # @see ClassMethods#value_semantics
+  # @see DSL.run
   #
   class Recipe
     attr_reader :attributes
@@ -294,13 +400,48 @@ module ValueSemantics
       ArrayOf.new(element_validator)
     end
 
-    def def_attr(*args)
-      __attributes << Attribute.define(*args)
+    def HashOf(key_validator_to_value_validator)
+      unless key_validator_to_value_validator.size.equal?(1)
+        raise ArgumentError, "HashOf() takes a hash with one key and one value"
+      end
+
+      HashOf.new(
+        key_validator_to_value_validator.keys.first,
+        key_validator_to_value_validator.values.first,
+      )
+    end
+
+    def ArrayCoercer(element_coercer)
+      ArrayCoercer.new(element_coercer)
+    end
+
+    #
+    # Defines one attribute.
+    #
+    # This is the method that gets called under the hood, when defining
+    # attributes the typical +#method_missing+ way.
+    #
+    # You can use this method directly if your attribute name results in invalid
+    # Ruby syntax. For example, if you want an attribute named +then+, you
+    # can do:
+    #
+    #     include ValueSemantics.for_attributes {
+    #       # Does not work:
+    #       then String, default: "whatever"
+    #       #=> SyntaxError: syntax error, unexpected `then'
+    #
+    #       # Works:
+    #       def_attr :then, String, default: "whatever"
+    #     }
+    #
+    #
+    def def_attr(*args, **kwargs)
+      __attributes << Attribute.define(*args, **kwargs)
     end
 
-    def method_missing(name, *args)
+    def method_missing(name, *args, **kwargs)
       if respond_to_missing?(name)
-        def_attr(name, *args)
+        def_attr(name, *args, **kwargs)
       else
         super
       end
@@ -366,4 +507,63 @@ module ValueSemantics
     end
   end
 
+  #
+  # Validator that matches +Hash+es with homogeneous keys and values
+  #
+  class HashOf
+    attr_reader :key_validator, :value_validator
+
+    def initialize(key_validator, value_validator)
+      @key_validator, @value_validator = key_validator, value_validator
+      freeze
+    end
+
+    # @return [Boolean]
+    def ===(value)
+      Hash === value && value.all? do |key, value|
+        key_validator === key && value_validator === value
+      end
+    end
+  end
+
+  class ArrayCoercer
+    attr_reader :element_coercer
+
+    def initialize(element_coercer = nil)
+      @element_coercer = element_coercer
+      freeze
+    end
+
+    def call(obj)
+      if obj.respond_to?(:to_a)
+        array = obj.to_a
+        if element_coercer
+          array.map { |element| element_coercer.call(element) }
+        else
+          array
+        end
+      else
+        obj
+      end
+    end
+  end
+
+  #
+  # ValueSemantics equivalent of the Struct class from the Ruby standard
+  # library
+  #
+  class Struct
+    #
+    # Creates a new Class with ValueSemantics mixed in
+    #
+    # @yield a block containing ValueSemantics DSL
+    # @return [Class] the newly created class
+    #
+    def self.new(&block)
+      klass = Class.new
+      klass.include(ValueSemantics.for_attributes(&block))
+      klass
+    end
+  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.1.0"
+  VERSION = "3.5.0"
 end

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: value_semantics
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Tom Dalling
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2019-06-30 00:00:00.000000000 Z
+date: 2020-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
 - !ruby/object:Gem::Dependency
@@ -30,14 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.7.0
+        version: '3.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.7.0
+        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
@@ -94,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: eceval
+  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'
 description: "\n    Generates modules that provide conventional value semantics for
   a given set of attributes.\n    The behaviour is similar to an immutable `Struct`
   class,\n    plus extensible, lightweight validation and coercion.\n  "
@@ -103,23 +131,20 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
 - CHANGELOG.md
-- Gemfile
 - LICENSE.txt
 - README.md
-- bin/console
-- bin/setup
-- bin/test
 - lib/value_semantics.rb
+- lib/value_semantics/monkey_patched.rb
 - lib/value_semantics/version.rb
-- value_semantics.gemspec
 homepage: https://github.com/tomdalling/value_semantics
 licenses:
 - MIT
-metadata: {}
+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.5.0/README.md
+  source_code_uri: https://github.com/tomdalling/value_semantics
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -135,7 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.4
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: Makes value classes, with lightweight validation and coercion.

data/.gitignore

@@ -1,12 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-# rspec failure tracking
-.rspec_status

data/.rspec

@@ -1,2 +0,0 @@
---format documentation
---color

data/.travis.yml

@@ -1,24 +0,0 @@
-language: ruby
-script: bin/test
-
-# test old Ruby versions WITHOUT mutation testing
-rvm:
-  - 2.3.8
-  - 2.4.5
-  - 2.5.3
-env: MUTATION_TEST=false
-
-# test the latest Ruby version WITH mutation testing
-matrix:
-  include:
-  - rvm: 2.6.0
-    env: MUTATION_TEST=true
-
-# deploy gem on tagged commits, on the latest Ruby version only
-deploy:
-  provider: rubygems
-  on:
-    tags: true
-    env: MUTATION_TEST=true
-  api_key:
-    secure: nL74QuUczEpA0qbhSBN2zjGdviWgKB3wR6vFvwervv1MZNWmwOQUYe99Oq9kPeyc8/x2MR/H6PQm5qbrk/WAfRede01WxlZ/EBUW+9CYGrxcBsGONx9IULO8A0I8/yN/YJHW2vjo3dfR66EwVsXTVWq8U63PRRcwJIyTqnIiUm2sxauMQoPRBbXG+pD9v/EJSn3ugpdtxp0lVYDn8LDKk5Ho4/wbpY4ML11XUJa9mz9CyR/GsAzdy5FTXaDMOwuWOVEx9cab7m4qPOBhmlJY4TrmooFpxTxRwChcvByjq1IboEd2M3RT5on7Q/xDTlHSOuT0OS8mnS2AocGT4a1gC+W/xOlghgEcN+xs2V5mfucR6+iUYlCy32uz1w3ey7T2X5xN4ubut09r1xLi7eu1NisAoAc+GOJ4TIxQNqkeRhY4X/fs8j7SMfOEMDr6pPxSLKZxgSvExt+IbdcZD/uQ7rTBQkadYCbc9MX5dHazBievmar3ZsFffbIf+n13FVDXsaPgRt7DlFM5dqGrEwVwt1jFRhdFuDCjkj4QWOLn7E1uY3XqgrqGvgUBlF8Znwc6qicW8zxV4SIWhqIzCOH6L9WIZGLHNq0remoCd9sq9Ter9av3jL+6UmZRRAr+JceeZfZmsYIXKomECzleM9FXMx7FXlpjJKOlf3JnrfeCTwI=

data/Gemfile

@@ -1,8 +0,0 @@
-source "https://rubygems.org"
-
-source 'https://oss:fLUos7k6c7Ak7zjhwbYphPJbwBk1Uuew@gem.mutant.dev' do
-  gem 'mutant-license'
-end
-
-# Specify your gem's dependencies in the gemspec
-gemspec

data/bin/console

@@ -1,14 +0,0 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "value_semantics"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here

data/bin/test

@@ -1,19 +0,0 @@
-#!/bin/bash
-set -ue
-
-MUTANT_PATTERN=${1:-ValueSemantics*}
-
-# if $MUTATION_TEST is false, just run RSpec
-if [[ "${MUTATION_TEST:-true}" == "false" ]] ; then
-    bundle exec rspec
-else
-    bundle exec mutant \
-        --include lib \
-        --require value_semantics \
-        --use rspec "$MUTANT_PATTERN" \
-        # Mutant 0.8.24 introduces new mutations that cause infinite recursion inside
-        # #method_missing. These --ignore-subject lines prevent that from happening
-        #--ignore-subject "ValueSemantics::DSL#method_missing" \
-        #--ignore-subject "ValueSemantics::DSL#respond_to_missing?" \
-        #--ignore-subject "ValueSemantics::DSL#def_attr" \
-fi

data/value_semantics.gemspec

@@ -1,34 +0,0 @@
-# coding: utf-8
-lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "value_semantics/version"
-
-Gem::Specification.new do |spec|
-  spec.name          = "value_semantics"
-  spec.version       = ValueSemantics::VERSION
-  spec.authors       = ["Tom Dalling"]
-  spec.email         = [["tom", "@", "tomdalling.com"].join]
-
-  spec.summary       = %q{Makes value classes, with lightweight validation and coercion.}
-  spec.description   = %q{
-    Generates modules that provide conventional value semantics for a given set of attributes.
-    The behaviour is similar to an immutable `Struct` class,
-    plus extensible, lightweight validation and coercion.
-  }
-  spec.homepage      = "https://github.com/tomdalling/value_semantics"
-  spec.license       = "MIT"
-
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "bundler", "~> 1.15"
-  spec.add_development_dependency "rspec", "~> 3.7.0"
-  spec.add_development_dependency "mutant-rspec"
-  spec.add_development_dependency "yard"
-  spec.add_development_dependency "byebug"
-  spec.add_development_dependency "gem-release"
-end