value_semantics 3.2.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcbb8468dcb54cae31c758fd34f4560e83efd8817a7d5eeb242e8b15293a12f5
-  data.tar.gz: 9cc2375503098535a28735cf97b044a8374fe819b41a8d4ebc0e43df0125ac0c
+  metadata.gz: 8d3795e585d271a6b0b784ef28931a16ae7f1846b13f7d307bf97d9d175c5384
+  data.tar.gz: 8289168c0be7e6cd00e24e59239a9ab8a2026fc42895007f33388d6ffa67add4
 SHA512:
-  metadata.gz: 0235750ae8ccce0830e75cf1b5be71b5bfb1417d71beb035484288648e26b07877538c47adf871f7b7725a736448192ce21884446aa2b58b8ce56edb4eed6013
-  data.tar.gz: d8f9c0cf27b34aa724e628129f883baf4b0d3ef7ae9772ee55c7904691e68deb6723b824b5b50456f73a4093f7a2b2ca48c907c938f14cb75a1deb8786a46fde
+  metadata.gz: 1b2520d80b112810e2b257920d591d4657cd9da26007307492cceac3321149b266bb310fba7c49e957d21a31e92bc041668bd907820b906570efa704d02c7948
+  data.tar.gz: 9605e0334ff2ff61dbb1925983b44f1275fb3768196bb62dbed6a2ccd9f6590b6e22ff3555101b6283181b18173657d363d397f8f10d329b9e4dea21ef1eb73c

data/CHANGELOG.md

@@ -5,6 +5,87 @@ 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]`
+- `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

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-30 ((2459092j,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-30 22:27:12.237812 +1000>
 ```
 
 The `default` option is a single value.
@@ -148,15 +188,15 @@ 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: Some attributes of `Person` are invalid:
+#=*       - name: 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: Some attributes of `Person` are invalid:
+#=*       - birthday: "hello"
 ```
 
 
@@ -168,13 +208,18 @@ 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)
+
+    # RangeOf: validates ranges
+    levels RangeOf(Integer)
+
     # Either: value must match at least one of a list of validators
     color Either(Integer, String, nil)
 
@@ -186,9 +231,12 @@ end
 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} levels=0..10 color="#FFAABB" wierd_attr=[true, false, true, true]>
 ```
 
 
@@ -197,22 +245,26 @@ 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: Some attributes of `Server` are invalid:
+#=*       - address: "127.0.0.999"
 ```
 
 Default attribute values also pass through validation.
@@ -224,46 +276,48 @@ Coercion
 Coercion allows non-standard or "convenience" values to be converted into
 proper, valid values, where possible.
 
-For example, an object with an `IPAddr` attribute may allow string values,
-which are then coerced into `IPAddr` objects.
+For example, an object with an `Pathname` attribute may allow string values,
+which are then coerced into `Pathname` objects.
 
 Using the option `coerce: true`,
 coercion happens through a custom class method called `coerce_#{attr}`,
 which takes the raw value as an argument, and returns the coerced value.
 
 ```ruby
-class Server
+require 'pathname'
+
+class Document
   include ValueSemantics.for_attributes {
-    address IPAddr, coerce: true
+    path Pathname, coerce: true
   }
 
-  def self.coerce_address(value)
+  def self.coerce_path(value)
     if value.is_a?(String)
-      IPAddr.new(value)
+      Pathname.new(value)
     else
       value
     end
   end
 end
 
-Server.new(address: '127.0.0.1')
-#=> #<Server address=#<IPAddr: IPv4:127.0.0.1/255.255.255.255>>
+Document.new(path: '~/Documents/whatever.doc')
+#=> #<Document path=#<Pathname:~/Documents/whatever.doc>>
 
-Server.new(address: IPAddr.new('127.0.0.1'))
-#=> #<Server address=#<IPAddr: IPv4:127.0.0.1/255.255.255.255>>
+Document.new(path: Pathname.new('~/Documents/whatever.doc'))
+#=> #<Document path=#<Pathname:~/Documents/whatever.doc>>
 
-Server.new(address: 42)
-#=> ArgumentError:
-#=>     Value for attribute 'address' is not valid: 42
+Document.new(path: 42)
+#=> !!! ValueSemantics::InvalidValue: Some attributes of `Document` are invalid:
+#=*       - path: 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 +325,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 +355,85 @@ 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.
+
+
+## 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 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
+  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 },
+      voiced_by: 'Samuel E. Wright',  # this attr will be ignored
+    }, {
+      '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
@@ -311,11 +443,41 @@ one step, similar to how `Struct` works from the Ruby standard library. For
 example:
 
 ```ruby
-Cat = ValueSemantics::Struct.new do
-  name String, default: "Mittens"
+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:461: syntax error, unexpected `then'
+#=*         then String
+#=*         ^~~~
+
 
-Cat.new.name #=> "Mittens"
+# This will work
+class Conditional
+  include ValueSemantics.for_attributes {
+    def_attr :then, String
+    def_attr :else, String
+  }
+end
 ```
 
 
@@ -341,7 +503,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 and helpful built-in validators and coercers
+ - Implement automatic freezing of value objects (must be opt-in)
 
 ## License