value_semantics 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17f5d6eaef0f928cf467ac69b5dc9d4f0dfcc09a6991ad460e44f394c5b94d87
-  data.tar.gz: c85d1e46558e4599e52df186a5b45f47193cf88246c4267c76b46f5f959f9f55
+  metadata.gz: 36400a694002cc8c879dfbad099d365e2674edf63ad258794094e2bb41f894da
+  data.tar.gz: f8f67ee234971124bcb65e487d59ed3126c8f51406b1bc4cc9d93eb1d70a5262
 SHA512:
-  metadata.gz: 3cd1bfb5150cbb4fef561da3d433dde03d4a4432253f697c94790ac6e30832a1901bc5989f8a48e062f55a9a80f5c9b19cdf99b20b16ac3704e872ebd4851057
-  data.tar.gz: bd16975818cb48f84cf07472a4723ffe6b04a74036d52f6a7e3c3fe8a5d04b4ef6270a6ea7d2a25ff137b56d3a3905392706ea91825134b7c7630a1c985fc53b
+  metadata.gz: 9d8becb2999466ceb24b0c9e6139ab089a64f019304c8803e6412e6a4818965dac59c601fc65f950c7e29cd5f4e27895a37e677baac6054e554e4fe749f2b5a6
+  data.tar.gz: 67d37d2f3fe4f07a6c54fdec2546e3a2b2e12ee92b1aa69a914382fee08ad9b0a2bfc00948e38f1b17b1608a6247763e507e255640add73c0ea0a3c5d6bac9b0

data/.travis.yml

@@ -1,10 +1,13 @@
 language: ruby
 rvm:
-- 2.4.1
+  - 2.3.7
+  - 2.4.4
+  - 2.5.1
 script: bundle exec rspec
 deploy:
   provider: rubygems
   on:
     tags: true
+    rvm: 2.5.1
   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

@@ -1,4 +1,7 @@
-# ValueSemantics
+[![Build Status](https://travis-ci.org/tomdalling/value_semantics.svg?branch=master)](https://travis-ci.org/tomdalling/value_semantics)
+
+ValueSemantics
+==============
 
 Create value classes quickly, with all the [conventions of a good value object](https://github.com/zverok/good-value-object).
 
@@ -10,7 +13,9 @@ These are intended for internal use, as opposed to validating user input like Ac
 Invalid or missing attributes cause an exception intended for developers,
 not an error message intended for the user.
 
-## Basic Usage
+
+Basic Usage
+-----------
 
 ```ruby
 require 'value_semantics'
@@ -62,10 +67,15 @@ mandatory due to Ruby's precedence rules.
 The `do`/`end` syntax will not work unless you surround the whole thing with parenthesis.
 
 
-## Validation (Types)
+Validation (Types)
+------------------
+
+Each attribute may optionally have a validator, to check that values are correct.
 
 Validators are objects that implement the `===` method,
-which means you can use `Class` objects (like `String`) and also `Regexp` objects:
+which means you can use `Class` objects (like `String`),
+and also things like regular expressions.
+Anything that you can use in a `case`/`when` expression will work.
 
 ```ruby
 class Person
@@ -86,6 +96,41 @@ Person.new(birthday: "hello", ...)
 #=>     Value for attribute 'birthday' is not valid: "hello"
 ```
 
+
+### Built-in Validators
+
+The ValueSemantics DSL comes with a small number of built-in validators,
+for common situations:
+
+```ruby
+class LightSwitch
+  include ValueSemantics.for_attributes {
+
+    # Boolean: only allows `true` or `false`
+    on? Boolean()
+
+    # ArrayOf: validates elements in an array
+    light_ids ArrayOf(Integer)
+
+    # Either: value must match at least one of a list of validators
+    color Either(Integer, String, nil)
+
+    # these validators are composable
+    wierd_attr Either(Boolean(), ArrayOf(Boolean()))
+  }
+end
+
+LightSwitch.new(
+  on?: true,
+  light_ids: [11, 12, 13],
+  color: "#FFAABB",
+  wierd_attr: [true, false, true, true],
+)
+```
+
+
+### Custom Validators
+
 A custom validator might look something like this:
 
 ```ruby
@@ -110,70 +155,78 @@ Person.new(age: 8)
 Default attribute values also pass through validation.
 
 
-## Coercion
+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.
 
-Coercion blocks can convert invalid values into valid ones, where possible.
+To implement coercion, define a class method called `coerce_#{attr}` which
+accepts a raw value, and returns the coerced value.
 
 ```ruby
 class Server
   include ValueSemantics.for_attributes {
-    address IPAddr do |value|
-      if value.is_a?(String)
-        IPAddr.new(value)
-      else
-        value
-      end
-    end
+    address IPAddr
   }
+
+  def self.coerce_address(value)
+    if value.is_a?(String)
+      IPAddr.new(value)
+    else
+      value
+    end
+  end
 end
 
-Server.new(address: '127.0.0.1')  # works
-Server.new(address: IPAddr.new('127.0.0.1'))  # works
+Server.new(address: '127.0.0.1')
+#=> #<Server address=#<IPAddr: IPv4:127.0.0.1/255.255.255.255>>
+
+Server.new(address: IPAddr.new('127.0.0.1'))
+#=> #<Server address=#<IPAddr: IPv4:127.0.0.1/255.255.255.255>>
+
 Server.new(address: 42)
 #=> ArgumentError:
 #=>     Value for attribute 'address' is not valid: 42
 ```
 
-If coercion is not possible, the value is to returned unchanged, allowing the validator to fail.
-Another option is to raise an error within the coercion block.
+If coercion is not possible, you can return the value unchanged,
+allowing the validator to fail.
+Another option is to raise an error within the coercion method.
 
 Coercion happens before validation.
 Default attribute values also pass through coercion.
 
-The coercion block runs in the context of the value object,
-so you can call methods from the value object.
-For example:
 
-```
-class Server
+## All Together
+
+```ruby
+class Person
   include ValueSemantics.for_attributes {
-    address IPAddr do |value|
-      coerce_address(value)
-    end
+    name String, default: "Anon Emous"
+    birthday Either(Date, nil)
   }
 
-  def coerce_address(value)
+  def self.coerce_birthday(value)
     if value.is_a?(String)
-      IPAddr.new(value)
+      Date.parse(value)
     else
       value
     end
   end
 end
-```
 
-## All Together
+Person.new(name: "Tom", birthday: "2020-12-25")
+#=> #<Person name="Tom" birthday=#<Date: 2020-12-25 ((2459209j,0s,0n),+0s,2299161j)>>
 
-```ruby
-class Coordinate
-  include ValueSemantics.for_attributes {
-    latitude Float, default: 0 { |value| value.to_f }
-    longitude Float, default: 0 { |value| value.to_f }
-  }
-end
+Person.new(birthday: Date.today)
+#=> #<Person name="Anon Emous" birthday=#<Date: 2018-09-04 ((2458366j,0s,0n),+0s,2299161j)>>
 
-Coordinate.new(longitude: "123")
-#=> #<Coordinate latitude=0.0 longitude=123.0>
+Person.new(birthday: nil)
+#=> #<Person name="Anon Emous" birthday=nil>
 ```
 
 

data/lib/value_semantics/version.rb

@@ -1,3 +1,3 @@
 module ValueSemantics
-  VERSION = "0.1.1"
+  VERSION = "1.0.0"
 end

data/lib/value_semantics.rb

@@ -32,7 +32,7 @@ module ValueSemantics
       remaining_attrs = given_attrs.dup
 
       self.class.attributes.each do |attr|
-        key, value = attr.determine_from!(remaining_attrs, self)
+        key, value = attr.determine_from!(remaining_attrs, self.class)
         instance_variable_set(attr.instance_variable, value)
         remaining_attrs.delete(key)
       end
@@ -75,18 +75,17 @@ module ValueSemantics
   end
 
   class Attribute
-    attr_reader :name, :has_default, :default_value, :coercer
+    attr_reader :name, :has_default, :default_value
 
-    def initialize(name:, has_default:, default_value:, validator:, coercer:)
+    def initialize(name:, has_default:, default_value:, validator:)
       @name = name.to_sym
       @has_default = has_default
       @default_value = default_value
       @validator = validator
-      @coercer = coercer
       freeze
     end
 
-    def determine_from!(attr_hash, value_object)
+    def determine_from!(attr_hash, klass)
       raw_value = attr_hash.fetch(name) do
         if has_default
           default_value
@@ -95,7 +94,7 @@ module ValueSemantics
         end
       end
 
-      coerced_value = value_object.instance_exec(raw_value, &coercer)
+      coerced_value = coerce(raw_value, klass)
 
       if validate?(coerced_value)
         [name, coerced_value]
@@ -104,6 +103,14 @@ module ValueSemantics
       end
     end
 
+    def coerce(attr_value, klass)
+      if klass.respond_to?(coercion_method)
+        klass.public_send(coercion_method, attr_value)
+      else
+        attr_value
+      end
+    end
+
     def default_value
       if has_default
         @default_value
@@ -119,6 +126,10 @@ module ValueSemantics
     def instance_variable
       '@' + name.to_s.chomp('!').chomp('?')
     end
+
+    def coercion_method
+      "coerce_#{name}"
+    end
   end
 
   class DSL
@@ -136,29 +147,83 @@ module ValueSemantics
       @__attributes = []
     end
 
-    def method_missing(attr_name, validator=AnythingValidator,
-      default: NOT_SPECIFIED, &coercion_block)
+    def Boolean
+      Boolean
+    end
+
+    def Either(*subvalidators)
+      Either.new(subvalidators)
+    end
+
+    def Anything
+      Anything
+    end
 
+    def ArrayOf(element_validator)
+      ArrayOf.new(element_validator)
+    end
+
+    def declare_attribute(attr_name, validator=Anything, default: NOT_SPECIFIED)
       __attributes << Attribute.new(
         name: attr_name,
         has_default: default != NOT_SPECIFIED,
         default_value: default,
         validator: validator,
-        coercer: coercion_block || IdentityCoercer,
       )
     end
 
+    def method_missing(name, *args, &block)
+      if respond_to_missing?(name)
+        declare_attribute(name, *args, &block)
+      else
+        super
+      end
+    end
+
     def respond_to_missing?(method_name, include_private = false)
-      true
+      first_letter = method_name.to_s[0]
+      (first_letter == first_letter.downcase) || super
     end
   end
 
-  module AnythingValidator
+  module Boolean
+    extend self
+
+    def ===(value)
+      true.eql?(value) || false.eql?(value)
+    end
+  end
+
+  module Anything
     def self.===(value)
       true
     end
   end
 
-  IdentityCoercer = ->(value) { value }
+  class Either
+    attr_reader :subvalidators
+
+    def initialize(subvalidators)
+      @subvalidators = subvalidators
+      freeze
+    end
+
+    def ===(value)
+      subvalidators.any? { |sv| sv === value }
+    end
+  end
+
+  class ArrayOf
+    attr_reader :element_validator
+
+    def initialize(element_validator)
+      @element_validator = element_validator
+      freeze
+    end
+
+    def ===(value)
+      Array === value && value.all? { |element| element_validator === element }
+    end
+  end
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: value_semantics
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Tom Dalling
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-08-22 00:00:00.000000000 Z
+date: 2018-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler