value_semantics 2.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17ee24bc8ffd744493e9957a4cb7ee0071f0c33aa8560b3ed36689575b9c0ab1
-  data.tar.gz: 05da8d260966f9257578f0ebf3891ba447b51032709bb75b39bdacba3e081961
+  metadata.gz: 1b538b4f5ab14c310ffdbc26ccb92cb9b47806126d0bc77ef466e2d9e7d64fcb
+  data.tar.gz: 85a0542f08c4a832b21acf75a697f999b7eae42f6a8989ae8c1d17838b76fd8a
 SHA512:
-  metadata.gz: 4a4da5150969146f5fd8cb06a17f8e43b1c897cd40f228cdddd7b2a8367fdbbceeacc66843668bf74a48575d72f752d3f24fd101c2ac7e946335688a1eec95a3
-  data.tar.gz: c0e71a37be6df7bcafa4833f7b7cea4304468818a4391e020770c6f85e16edaf68a56c84c572f3bd26399aa85b2dc149abb48660d82750a656d746d87da5a16a
+  metadata.gz: 3f869be70a14418aa6247cca5222e53aed3bc7d4b506f1231e4f010b382cd962d08558a92506b47817600acca04d0f5cad1c4f9375ca6c249042ada9ea709fb3
+  data.tar.gz: 3c26016b77c88eb8ae851dadaf2853eb0792beb68a8dfb2961dca77d2b98414e6ba4f31ba0141a23544fb18dfcc73425cc9f1737df6539933e1b815a6037f564

data/.travis.yml

@@ -1,13 +1,24 @@
 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.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
-    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/README.md

@@ -103,7 +103,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 +164,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 +174,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
 

data/bin/test

@@ -0,0 +1,19 @@
+#!/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/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
@@ -76,12 +141,20 @@ module ValueSemantics
     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 +162,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 +228,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 +268,8 @@ module ValueSemantics
       @__attributes = []
     end
 
-    def Boolean
-      Boolean
+    def Bool
+      Bool
     end
 
     def Either(*subvalidators)
@@ -159,30 +284,8 @@ 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)
+      __attributes << Attribute.define(*args)
     end
 
     def method_missing(name, *args)
@@ -194,25 +297,34 @@ module ValueSemantics
     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 +333,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,6 +350,7 @@ module ValueSemantics
       freeze
     end
 
+    # @return [Boolean]
     def ===(value)
       Array === value && value.all? { |element| element_validator === element }
     end

data/lib/value_semantics/version.rb

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

data/value_semantics.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
   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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: value_semantics
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Tom Dalling
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-12-21 00:00:00.000000000 Z
+date: 2019-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -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
@@ -97,8 +111,8 @@ files:
 - 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,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.0
+rubygems_version: 3.0.2
 signing_key: 
 specification_version: 4
 summary: Create value classes quickly, with all the proper conventions.

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"