value_semantics 3.5.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '069ef7cc15f7d9b6eae3af432d486595bfa3f89c0f68ce68ab3eda2fb5d5f9f4'
-  data.tar.gz: f8d1839f7176743cb9d7a144d5452f999048a03a5d1d86d8b86b81b648a7bfd3
+  metadata.gz: 8d3795e585d271a6b0b784ef28931a16ae7f1846b13f7d307bf97d9d175c5384
+  data.tar.gz: 8289168c0be7e6cd00e24e59239a9ab8a2026fc42895007f33388d6ffa67add4
 SHA512:
-  metadata.gz: cea465484d60d6343815072b4e81639e399b20ce528a12ce643be39e3a06051fdaddb4c58037ffac5237f7c62b823b49d888bc8d6fed925b181515751b4cfb46
-  data.tar.gz: 553a990a508956e7a2b6f96ea2ac65ee97737bc6ea5da1ea337f9d0d06b294aa61fb3e10ef1d8ce6ac5fff826b3f1bdbf17b9e805ac38b933308152929335efd
+  metadata.gz: 1b2520d80b112810e2b257920d591d4657cd9da26007307492cceac3321149b266bb310fba7c49e957d21a31e92bc041668bd907820b906570efa704d02c7948
+  data.tar.gz: 9605e0334ff2ff61dbb1925983b44f1275fb3768196bb62dbed6a2ccd9f6590b6e22ff3555101b6283181b18173657d363d397f8f10d329b9e4dea21ef1eb73c

data/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.6.0] - 2020-09-01
+### Added
+- `RangeOf` built-in validator, for validating `Range` objects
+- `HashCoercer` built-in coercer for homogeneous `Hash` objects
+### Changed
+- Optimised speed of value object initialization. It is now roughly 3x
+  slower than that of a hand-written class, which is 2-3x faster than
+  the previous version.
+
+- Optimised memory allocation in object initialization. The happy path
+  (no exceptions raised) only allocates a single array object, under
+  normal circumstances. Extra allocations are likely caused by custom
+  validators, coercers, and default generators.
+
+- Exceptions raised when initialising a value object are now
+  aggregated. Instead of telling you the problematic attributes one at
+  a time, you will get a list of all offending attributes in the
+  exception message. This applies to `MissingAttributes`,
+  `InvalidValue` and `UnrecognizedAttributes`. These will probably be
+  combined into a single exception in v4.0, so you can see all the
+  initialization problems at once.
+
+- The exceptions `ValueSemantics::MissingAttributes` and
+  `ValueSemantics::InvalidValue` are now raised from inside
+  `initialize`. They were previously raised from inside of
+  `ValueSemantics::Attribute.determine_from!` which is an internal
+  implementation detail that is basically gibberish to any developer
+  reading it. The stack trace for this exception reads much better.
+
+- The exception `ValueSemantics::UnrecognizedAttributes` is now raised
+  instead of `ValueSemantics::MissingAttributes` in the situation
+  where both exceptions would be raised. This makes it easier to debug
+  the problem where you attempt to initialize a value object using a
+  hash with string keys instead of symbol keys.
+
+- The coercer returned from the `.coercer` class method is now
+  smarter. It handles string keys, handles objects that can be
+  converted to hashes.
+### Deprecated
+- `ValueSemantics::Attribute#determine_from!`. This was an internal
+  implementation detail, which is no longer used internally. Use the
+  `name`, `#coerce`, `#optional?`, `#default_generator` and
+  `#validate?` methods directly if you want to extract an attribute
+  from a hash.
+- `ValueSemantics::NoDefaultError`. Use `Attribute#optional?` to check
+  whether there is a default.
+
+
+
 ## [3.5.0] - 2020-08-17
 ### Added
 - Square bracket attr reader like `person[:name]`

data/README.md

@@ -50,7 +50,7 @@ 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: 2020-08-04 ((2459066j,0s,0n),+0s,2299161j)>>
+#=> #<Person name="Anon Emous" birthday=#<Date: 2020-08-30 ((2459092j,0s,0n),+0s,2299161j)>>
 
 Person.new(birthday: nil)
 #=> #<Person name="Anon Emous" birthday=nil>
@@ -159,7 +159,7 @@ class Cat
 end
 
 Cat.new
-#=> #<Cat paws=4 born_at=2020-08-04 00:16:35.15632 +1000>
+#=> #<Cat paws=4 born_at=2020-08-30 22:27:12.237812 +1000>
 ```
 
 The `default` option is a single value.
@@ -190,11 +190,13 @@ end
 
 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
+#=> !!! ValueSemantics::InvalidValue: Some attributes of `Person` are invalid:
+#=*       - name: 5
 
 Person.new(name: 'Tom', birthday: "1970-01-01")  # works
 Person.new(name: 'Tom', birthday: "hello")
-#=> !!! ValueSemantics::InvalidValue: Attribute `Person#birthday` is invalid: "hello"
+#=> !!! ValueSemantics::InvalidValue: Some attributes of `Person` are invalid:
+#=*       - birthday: "hello"
 ```
 
 
@@ -215,6 +217,9 @@ class LightSwitch
     # HashOf: validates keys/values of a homogeneous hash
     toggle_stats HashOf(Symbol => Integer)
 
+    # RangeOf: validates ranges
+    levels RangeOf(Integer)
+
     # Either: value must match at least one of a list of validators
     color Either(Integer, String, nil)
 
@@ -227,10 +232,11 @@ LightSwitch.new(
   on?: true,
   light_ids: [11, 12, 13],
   toggle_stats: { day: 42, night: 69 },
+  levels: (0..10),
   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]>
+#=> #<LightSwitch on?=true light_ids=[11, 12, 13] toggle_stats={:day=>42, :night=>69} levels=0..10 color="#FFAABB" wierd_attr=[true, false, true, true]>
 ```
 
 
@@ -257,7 +263,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"
+#=> !!! ValueSemantics::InvalidValue: Some attributes of `Server` are invalid:
+#=*       - address: "127.0.0.999"
 ```
 
 Default attribute values also pass through validation.
@@ -300,7 +307,8 @@ Document.new(path: Pathname.new('~/Documents/whatever.doc'))
 #=> #<Document path=#<Pathname:~/Documents/whatever.doc>>
 
 Document.new(path: 42)
-#=> !!! ValueSemantics::InvalidValue: Attribute `Document#path` is invalid: 42
+#=> !!! ValueSemantics::InvalidValue: Some attributes of `Document` are invalid:
+#=*       - path: 42
 ```
 
 You can also use any callable object as a coercer.
@@ -350,12 +358,45 @@ For example, the default value could be a string,
 which would then be coerced into an `Pathname` object.
 
 
+## Built-in Coercers
+
+ValueSemantics provides a few built-in coercer objects via the DSL.
+
+```ruby
+class Config
+  include ValueSemantics.for_attributes {
+    # ArrayCoercer: takes an element coercer
+    paths coerce: ArrayCoercer(Pathname.method(:new))
+
+    # HashCoercer: takes a key and value coercer
+    env coerce: HashCoercer(
+      keys: :to_sym.to_proc,
+      values: :to_i.to_proc,
+    )
+  }
+end
+
+config = Config.new(
+  paths: ['/a', '/b'],
+  env: { 'AAAA' => '1', 'BBBB' => '2' },
+)
+
+config.paths #=> [#<Pathname:/a>, #<Pathname:/b>]
+config.env #=> {:AAAA=>1, :BBBB=>2}
+```
+
+
 ## 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.
+works as expected, but coercion is not automatic.
+
+For nested coercion, use the `.coercer` class method that
+ValueSemantics provides. It returns a coercer object that accepts
+strings for attribute names, and will ignore attributes that the value
+class does not define, instead of raising an error.
+
+This works well in combination with `ArrayCoercer`.
 
 ```ruby
 class CrabClaw
@@ -380,11 +421,12 @@ end
 ocean = Ocean.new(
   crabs: [
     {
-      left_claw: { size: :small },
-      right_claw: { size: :small },
+      'left_claw' => { 'size' => :small },
+      'right_claw' => { 'size' => :small },
+      voiced_by: 'Samuel E. Wright',  # this attr will be ignored
     }, {
-      left_claw: { size: :big },
-      right_claw: { size: :big },
+      'left_claw' => { 'size' => :big },
+      'right_claw' => { 'size' => :big },
     }
   ]
 )
@@ -424,7 +466,7 @@ class Conditional
     else String
   }
 end
-#=> !!! SyntaxError: README.md:375: syntax error, unexpected `then'
+#=> !!! SyntaxError: README.md:461: syntax error, unexpected `then'
 #=*         then String
 #=*         ^~~~
 
@@ -468,7 +510,7 @@ 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
+ - Add new and helpful built-in validators and coercers
  - Implement automatic freezing of value objects (must be opt-in)
 
 ## License

data/lib/value_semantics.rb

@@ -1,11 +1,35 @@
+%w(
+  anything
+  array_coercer
+  array_of
+  attribute
+  bool
+  class_methods
+  dsl
+  either
+  hash_of
+  hash_coercer
+  instance_methods
+  range_of
+  recipe
+  struct
+  value_object_coercer
+  version
+).each do |filename|
+  require_relative "value_semantics/#{filename}"
+end
+
 module ValueSemantics
   class Error < StandardError; end
   class UnrecognizedAttributes < Error; end
-  class NoDefaultValue < Error; end
   class MissingAttributes < Error; end
   class InvalidValue < ArgumentError; end
 
-  NOT_SPECIFIED = Object.new.freeze
+  # @deprecated Use {Attribute::NOT_SPECIFIED} instead
+  NOT_SPECIFIED = Attribute::NOT_SPECIFIED
+
+  # @deprecated Use {Attribute#optional?} to check if there is a default or not
+  class NoDefaultValue < Error; end
 
   #
   # Creates a module via the DSL
@@ -75,495 +99,4 @@ module ValueSemantics
       private :value_semantics
     end
   end
-
-  #
-  # 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
-      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
-
-  #
-  # All the instance methods available on ValueSemantics objects
-  #
-  module InstanceMethods
-    #
-    # 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+.
-    #
-    # @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)
-        instance_variable_set(attr.instance_variable, value)
-        remaining_attrs.delete(key)
-      end
-
-      unless remaining_attrs.empty?
-        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
-
-    #
-    # 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.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
-      to_h.hash ^ self.class.hash
-    end
-
-    def inspect
-      attrs = to_h
-        .map { |key, value| "#{key}=#{value.inspect}" }
-        .join(" ")
-
-      "#<#{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
-
-    def deconstruct_keys(_)
-      to_h
-    end
-  end
-
-  #
-  # Represents a single attribute of a value class
-  #
-  class Attribute
-    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: NO_DEFAULT_GENERATOR,
-                   validator: Anything,
-                   coercer: nil)
-      @name = name.to_sym
-      @default_generator = default_generator
-      @validator = validator
-      @coercer = coercer
-      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 MissingAttributes, "Attribute `#{klass}\##{name}` has no value"
-        else
-          default_generator.call
-        end
-      end
-
-      coerced_value = coerce(raw_value, klass)
-
-      if validate?(coerced_value)
-        [name, coerced_value]
-      else
-        raise InvalidValue, "Attribute `#{klass}\##{name}` is invalid: #{coerced_value.inspect}"
-      end
-    end
-
-    def coerce(attr_value, klass)
-      return attr_value unless coercer # coercion not enabled
-
-      if coercer.equal?(true)
-        klass.public_send(coercion_method, attr_value)
-      else
-        coercer.call(attr_value)
-      end
-    end
-
-    def validate?(value)
-      validator === value
-    end
-
-    def instance_variable
-      '@' + name.to_s.chomp('!').chomp('?')
-    end
-
-    def coercion_method
-      "coerce_#{name}"
-    end
-  end
-
-  #
-  # 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
-
-    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)
-      Recipe.new(attributes: dsl.__attributes.freeze)
-    end
-
-    attr_reader :__attributes
-
-    def initialize
-      @__attributes = []
-    end
-
-    def Bool
-      Bool
-    end
-
-    def Either(*subvalidators)
-      Either.new(subvalidators)
-    end
-
-    def Anything
-      Anything
-    end
-
-    def ArrayOf(element_validator)
-      ArrayOf.new(element_validator)
-    end
-
-    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, **kwargs)
-      if respond_to_missing?(name)
-        def_attr(name, *args, **kwargs)
-      else
-        super
-      end
-    end
-
-    def respond_to_missing?(method_name, _include_private=nil)
-      first_letter = method_name.to_s.each_char.first
-      first_letter.eql?(first_letter.downcase)
-    end
-  end
-
-  #
-  # 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
-
-    def initialize(subvalidators)
-      @subvalidators = subvalidators
-      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
-
-    def initialize(element_validator)
-      @element_validator = element_validator
-      freeze
-    end
-
-    # @return [Boolean]
-    def ===(value)
-      Array === value && value.all? { |element| element_validator === element }
-    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