value_semantics 2.1.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17ee24bc8ffd744493e9957a4cb7ee0071f0c33aa8560b3ed36689575b9c0ab1
-  data.tar.gz: 05da8d260966f9257578f0ebf3891ba447b51032709bb75b39bdacba3e081961
+  metadata.gz: f122fa566277c213c7eb2a31b38af94d4287b1688d91da91bd5eea8044a041ba
+  data.tar.gz: 371bc15f0cc7449042b19d5064e4a28f76ec1d6c0aae2c64622adf3252621045
 SHA512:
-  metadata.gz: 4a4da5150969146f5fd8cb06a17f8e43b1c897cd40f228cdddd7b2a8367fdbbceeacc66843668bf74a48575d72f752d3f24fd101c2ac7e946335688a1eec95a3
-  data.tar.gz: c0e71a37be6df7bcafa4833f7b7cea4304468818a4391e020770c6f85e16edaf68a56c84c572f3bd26399aa85b2dc149abb48660d82750a656d746d87da5a16a
+  metadata.gz: a7ebe03be2de318e43027cc4d27ed737111654a5d74c0646f62691076e0f51938eb55966a3f04105f4a4c86d242a0134ca3f5fafa27089aedd4c51f2fb45abd9
+  data.tar.gz: ac4e7a9f938e0bd9193d4260a8c211db6a05554463b6312a6409499a8d22c7a34b281093cf2c487676fefd58915b21027a47c99a75619fb2b80c457672ced57e

data/.travis.yml

@@ -1,13 +1,25 @@
 language: ruby
+script: bin/test
+
+# test old Ruby versions WITHOUT mutation testing
 rvm:
-  - 2.3.7
-  - 2.4.4
-  - 2.5.1
-script: bin/mutation_test.sh
+  - 2.3.8
+  - 2.4.10
+  - 2.5.8
+  - 2.6.6
+env: MUTATION_TEST=false
+
+# test the latest Ruby version WITH mutation testing
+matrix:
+  include:
+  - rvm: 2.7.1
+    env: MUTATION_TEST=true
+
+# deploy gem on tagged commits, on the latest Ruby version only
 deploy:
   provider: rubygems
   on:
     tags: true
-    rvm: 2.5.1
+    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/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+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.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
+
+## [3.0.0] - 2019-01-27
+
+First public release

data/Gemfile

@@ -1,6 +1,8 @@
 source "https://rubygems.org"
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source 'https://oss:fLUos7k6c7Ak7zjhwbYphPJbwBk1Uuew@gem.mutant.dev' do
+  gem 'mutant-license'
+end
 
 # Specify your gem's dependencies in the gemspec
 gemspec

data/README.md

@@ -5,15 +5,20 @@
 ValueSemantics
 ==============
 
-Create value classes quickly, with all the [conventions of a good value object](https://github.com/zverok/good-value-object).
+A gem for making value classes.
 
-Generates modules that provide value semantics for a given set of attributes.
-Provides the behaviour of an immutable struct-like value class,
-with light-weight validation and coercion.
+Generates modules that provide [conventional value semantics](https://github.com/zverok/good-value-object) for a given set of attributes.
+The behaviour is similar to an immutable `Struct` class,
+plus extensible, lightweight validation and coercion.
 
 These are intended for internal use, as opposed to validating user input like ActiveRecord.
-Invalid or missing attributes cause an exception intended for developers,
-not an error message intended for the user.
+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].
+
+[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/
 
 
 Defining and Creating Value Objects
@@ -103,7 +108,7 @@ Defaults
 --------
 
 Defaults can be specified in one of two ways:
-the `:default` option, or the `default_generator` option.
+the `:default` option, or the `:default_generator` option.
 
 ```ruby
 class Cat
@@ -164,8 +169,8 @@ for common situations:
 class LightSwitch
   include ValueSemantics.for_attributes {
 
-    # Boolean: only allows `true` or `false`
-    on? Boolean()
+    # Bool: only allows `true` or `false`
+    on? Bool()
 
     # ArrayOf: validates elements in an array
     light_ids ArrayOf(Integer)
@@ -174,7 +179,7 @@ class LightSwitch
     color Either(Integer, String, nil)
 
     # these validators are composable
-    wierd_attr Either(Boolean(), ArrayOf(Boolean()))
+    wierd_attr Either(Bool(), ArrayOf(Bool()))
   }
 end
 
@@ -299,6 +304,21 @@ For example, the default value could be a string,
 which would then be coerced into an `IPAddr` object.
 
 
+## 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
+Cat = ValueSemantics::Struct.new do
+  name String, default: "Mittens"
+end
+
+Cat.new.name #=> "Mittens"
+```
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -321,6 +341,7 @@ 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.
 
 ## License
 

data/bin/test

@@ -0,0 +1,15 @@
+#!/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" \
+        --ignore-subject "ValueSemantics::Struct.new" # causes unfixable failure I don't want to deal with
+fi

data/lib/value_semantics.rb

@@ -1,39 +1,80 @@
 module ValueSemantics
+  class Error < StandardError; end
+  class UnrecognizedAttributes < Error; end
+  class NoDefaultValue < Error; end
+  class MissingAttributes < Error; end
+
   NOT_SPECIFIED = Object.new.freeze
 
+  #
+  # Creates a module via the DSL
+  #
+  # @yield The block containing the DSL
+  # @return [Module]
+  #
+  # @see DSL
+  # @see InstanceMethods
+  #
   def self.for_attributes(&block)
-    attributes = DSL.run(&block)
-    generate_module(attributes.freeze)
+    recipe = DSL.run(&block)
+    bake_module(recipe)
   end
 
-  def self.generate_module(attributes)
+  #
+  # Creates a module from a {Recipe}
+  #
+  # @param recipe [Recipe]
+  # @return [Module]
+  #
+  def self.bake_module(recipe)
     Module.new do
-      # include all the instance methods
-      include(Semantics)
+      const_set(:VALUE_SEMANTICS_RECIPE__, recipe)
+      include(InstanceMethods)
 
       # define the attr readers
-      attributes.each do |attr|
+      recipe.attributes.each do |attr|
         module_eval("def #{attr.name}; #{attr.instance_variable}; end")
       end
 
-      # define BaseClass.attributes class method
-      const_set(:ATTRIBUTES__, attributes)
       def self.included(base)
-        base.const_set(:ValueSemantics_Generated, self)
-        class << base
-          def attributes
-            self::ATTRIBUTES__
-          end
-        end
+        base.const_set(:ValueSemantics_Attributes, self)
+        base.extend(ClassMethods)
       end
     end
   end
 
-  module Semantics
+  #
+  # All the class methods available on ValueSemantics classes
+  #
+  # When a ValueSemantics module is included into a class,
+  # the class is extended by this module.
+  #
+  module ClassMethods
+    #
+    # @return [Recipe] the recipe used to build the ValueSemantics module that
+    #                  was included into this class.
+    #
+    def value_semantics
+      self::VALUE_SEMANTICS_RECIPE__
+    end
+  end
+
+  #
+  # All the instance methods available on ValueSemantics objects
+  #
+  module InstanceMethods
+    #
+    # 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
+    #
     def initialize(given_attrs = {})
       remaining_attrs = given_attrs.dup
 
-      self.class.attributes.each do |attr|
+      self.class.value_semantics.attributes.each do |attr|
         key, value = attr.determine_from!(remaining_attrs, self.class)
         instance_variable_set(attr.instance_variable, value)
         remaining_attrs.delete(key)
@@ -41,30 +82,54 @@ module ValueSemantics
 
       unless remaining_attrs.empty?
         unrecognised = remaining_attrs.keys.map(&:inspect).join(', ')
-        raise ArgumentError, "Unrecognised attributes: #{unrecognised}"
+        raise UnrecognizedAttributes, "Unrecognized attributes: #{unrecognised}"
       end
     end
 
+    #
+    # Creates a copy of this object, with the given attributes changed (non-destructive update)
+    #
+    # @param new_attrs [Hash] the attributes to change
+    # @return A new object, with the attribute changes applied
+    #
     def with(new_attrs)
       self.class.new(to_h.merge(new_attrs))
     end
 
+    #
+    # @return [Hash] all of the attributes
+    #
     def to_h
-      self.class.attributes
+      self.class.value_semantics.attributes
         .map { |attr| [attr.name, public_send(attr.name)] }
         .to_h
     end
 
+    #
+    # Loose equality
+    #
+    # @return [Boolean] whether all attributes are equal, and the object
+    #                   classes are ancestors of eachother in any way
+    #
     def ==(other)
       (other.is_a?(self.class) || is_a?(other.class)) && other.to_h.eql?(to_h)
     end
 
+    #
+    # Strict equality
+    #
+    # @return [Boolean] whether all attribuets are equal, and both objects
+    #                   has the exact same class
+    #
     def eql?(other)
       other.class.equal?(self.class) && other.to_h.eql?(to_h)
     end
 
+    #
+    # Unique-ish integer, based on attributes and class of the object
+    #
     def hash
-      @__hash ||= (to_h.hash ^ self.class.hash)
+      to_h.hash ^ self.class.hash
     end
 
     def inspect
@@ -74,14 +139,32 @@ module ValueSemantics
 
       "#<#{self.class} #{attrs}>"
     end
+
+    def pretty_print(pp)
+      pp.object_group(self) do
+        to_h.each do |attr, value|
+          pp.breakable
+          pp.text("#{attr}=")
+          pp.pp(value)
+        end
+      end
+    end
   end
 
+  #
+  # Represents a single attribute of a value class
+  #
   class Attribute
-    NO_DEFAULT_GENERATOR = ->{ raise "Attribute does not have a default value" }
+    NO_DEFAULT_GENERATOR = lambda do
+      raise NoDefaultValue, "Attribute does not have a default value"
+    end
 
     attr_reader :name, :validator, :coercer, :default_generator
 
-    def initialize(name:, default_generator:, validator:, coercer:)
+    def initialize(name:,
+                   default_generator: NO_DEFAULT_GENERATOR,
+                   validator: Anything,
+                   coercer: nil)
       @name = name.to_sym
       @default_generator = default_generator
       @validator = validator
@@ -89,10 +172,35 @@ module ValueSemantics
       freeze
     end
 
+    def self.define(name,
+                    validator=Anything,
+                    default: NOT_SPECIFIED,
+                    default_generator: nil,
+                    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"
+        elsif default_generator
+          default_generator
+        elsif !default.equal?(NOT_SPECIFIED)
+          ->{ default }
+        else
+          NO_DEFAULT_GENERATOR
+        end
+      end
+
+      new(
+        name: name,
+        validator: validator,
+        default_generator: generator,
+        coercer: coerce,
+      )
+    end
+
     def determine_from!(attr_hash, klass)
       raw_value = attr_hash.fetch(name) do
         if default_generator.equal?(NO_DEFAULT_GENERATOR)
-          raise ArgumentError, "Value missing for attribute '#{name}'"
+          raise MissingAttributes, "Value missing for attribute '#{name}'"
         else
           default_generator.call
         end
@@ -130,11 +238,38 @@ module ValueSemantics
     end
   end
 
+  #
+  # Contains all the configuration necessary to bake a ValueSemantics module
+  #
+  # @see ValueSemantics.bake_module
+  #
+  class Recipe
+    attr_reader :attributes
+
+    def initialize(attributes:)
+      @attributes = attributes
+      freeze
+    end
+  end
+
+  #
+  # Builds a {Recipe} via DSL methods
+  #
+  # DSL blocks are <code>instance_eval</code>d against an object of this class.
+  #
+  # @see Recipe
+  # @see ValueSemantics.for_attributes
+  #
   class DSL
+    #
+    # Builds a {Recipe} from a DSL block
+    #
+    # @yield to the block containing the DSL
+    # @return [Recipe]
     def self.run(&block)
       dsl = new
       dsl.instance_eval(&block)
-      dsl.__attributes
+      Recipe.new(attributes: dsl.__attributes.freeze)
     end
 
     attr_reader :__attributes
@@ -143,8 +278,8 @@ module ValueSemantics
       @__attributes = []
     end
 
-    def Boolean
-      Boolean
+    def Bool
+      Bool
     end
 
     def Either(*subvalidators)
@@ -159,60 +294,47 @@ module ValueSemantics
       ArrayOf.new(element_validator)
     end
 
-    def def_attr(attr_name,
-                 validator=Anything,
-                 default: NOT_SPECIFIED,
-                 default_generator: nil,
-                 coerce: nil
-                 )
-      generator = begin
-        if default_generator && !default.equal?(NOT_SPECIFIED)
-          raise ArgumentError, "Attribute '#{attr_name}' can not have both a default, and a default_generator"
-        elsif default_generator
-          default_generator
-        elsif !default.equal?(NOT_SPECIFIED)
-          ->{ default }
-        else
-          Attribute::NO_DEFAULT_GENERATOR
-        end
-      end
-
-      __attributes << Attribute.new(
-        name: attr_name,
-        validator: validator,
-        default_generator: generator,
-        coercer: coerce
-      )
+    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
     end
 
     def respond_to_missing?(method_name, _include_private=nil)
-      first_letter = method_name[0]
+      first_letter = method_name.to_s.each_char.first
       first_letter.eql?(first_letter.downcase)
     end
   end
 
-  module Boolean
-    extend self
-
-    def ===(value)
+  #
+  # Validator that only matches `true` and `false`
+  #
+  module Bool
+    # @return [Boolean]
+    def self.===(value)
       true.equal?(value) || false.equal?(value)
     end
   end
 
+  #
+  # Validator that matches any and all values
+  #
   module Anything
+    # @return [true]
     def self.===(_)
       true
     end
   end
 
+  #
+  # Validator that matches if any of the given subvalidators matches
+  #
   class Either
     attr_reader :subvalidators
 
@@ -221,11 +343,15 @@ module ValueSemantics
       freeze
     end
 
+    # @return [Boolean]
     def ===(value)
       subvalidators.any? { |sv| sv === value }
     end
   end
 
+  #
+  # Validator that matches arrays if each element matches a given subvalidator
+  #
   class ArrayOf
     attr_reader :element_validator
 
@@ -234,9 +360,28 @@ module ValueSemantics
       freeze
     end
 
+    # @return [Boolean]
     def ===(value)
       Array === value && value.all? { |element| element_validator === element }
     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/version.rb

@@ -1,3 +1,3 @@
 module ValueSemantics
-  VERSION = "2.1.0"
+  VERSION = "3.2.1"
 end

data/value_semantics.gemspec

@@ -9,13 +9,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Tom Dalling"]
   spec.email         = [["tom", "@", "tomdalling.com"].join]
 
-  spec.summary       = %q{Create value classes quickly, with all the proper conventions.}
+  spec.summary       = %q{Makes value classes, with lightweight validation and coercion.}
   spec.description   = %q{
-    Create value classes quickly, with all the proper conventions.
-
-    Generates modules that provide value semantics for a given set of attributes.
-    Provides the behaviour of an immutable struct-like value class,
-    with light-weight validation and coercion.
+    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"
@@ -27,9 +25,10 @@ Gem::Specification.new do |spec|
   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 "bundler", ">= 1.15"
+  spec.add_development_dependency "rspec", "~> 3.7"
   spec.add_development_dependency "mutant-rspec"
+  spec.add_development_dependency "yard"
   spec.add_development_dependency "byebug"
   spec.add_development_dependency "gem-release"
 end

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: value_semantics
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.2.1
 platform: ruby
 authors:
 - Tom Dalling
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-12-21 00:00:00.000000000 Z
+date: 2020-07-11 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,14 @@ 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: mutant-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -80,10 +94,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: "\n    Create value classes quickly, with all the proper conventions.\n\n
-  \   Generates modules that provide value semantics for a given set of attributes.\n
-  \   Provides the behaviour of an immutable struct-like value class,\n    with light-weight
-  validation and coercion.\n  "
+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  "
 email:
 - tom@tomdalling.com
 executables: []
@@ -93,12 +106,13 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - bin/console
-- bin/mutation_test.sh
 - bin/setup
+- bin/test
 - lib/value_semantics.rb
 - lib/value_semantics/version.rb
 - value_semantics.gemspec
@@ -121,8 +135,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.0
+rubyforge_project: 
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
-summary: Create value classes quickly, with all the proper conventions.
+summary: Makes value classes, with lightweight validation and coercion.
 test_files: []

data/bin/mutation_test.sh

@@ -1,6 +0,0 @@
-#!/bin/sh
-set -ue
-
-PATTERN=${1:-ValueSemantics*}
-
-bundle exec mutant --include lib --require value_semantics --use rspec "$PATTERN"