value_semantics 1.0.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d5af9c70cace0213a309865f7fb2eaf09759d3f654d530d577d9067ee8e025d
-  data.tar.gz: 31ef2d58e797173040691bc6ac57703751102c40519c8bcd4913f6fa24e97481
+  metadata.gz: 235fbd4782ce1bc943f12688408c20a5b6893e7b57882c63b725953115de74d3
+  data.tar.gz: 6adbdbcc36d8093fd323fb2d734557025df4b0dc9983e6ba343690a229dfed40
 SHA512:
-  metadata.gz: 051b338a932d31e4e74a2699bd45a9a740e7fe8673f8833e566254c4be8262f90947160784db895d1706c40a8f910db21ea0999a90a3df6d65481dd60932a626
-  data.tar.gz: 8860483b155c84402fc6964967b29ba1cef4f6a1b46409752b714d139c78625b02d0bcf184a4eb671bb2b94c4b4442938fcacec32e07f854f934e2defb87e811
+  metadata.gz: 179eed3a45a75b8f6546c99fd4fdcd2cb987885a4b00f36caa359a3e7b19854dd0401d3b6f3c4cd5b108256492be94d068dfa1765eb6a6844b9ccd610212cffe
+  data.tar.gz: c9eefd7b84e63507513c2d3b88469730c346899a2a7ae109bc1159f2ed764d71102a7dbbd9e7ae0ea9d2caad1ee82c1c6b740c69eb508caa50571687d0f51c75

data/README.md

@@ -166,13 +166,14 @@ proper, valid values, where possible.
 For example, an object with an `IPAddr` attribute may allow string values,
 which are then coerced into `IPAddr` objects.
 
-To implement coercion, define a class method called `coerce_#{attr}` which
-accepts a raw value, and returns the coerced value.
+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
   include ValueSemantics.for_attributes {
-    address IPAddr
+    address IPAddr, coerce: true
   }
 
   def self.coerce_address(value)
@@ -195,12 +196,51 @@ Server.new(address: 42)
 #=>     Value for attribute 'address' is not valid: 42
 ```
 
-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.
+You can also use any callable object as a coercer.
+That means, you could use a lambda:
+
+```ruby
+class Server
+  include ValueSemantics.for_attributes {
+    address IPAddr, coerce: ->(value) { IPAddr.new(value) }
+  }
+end
+```
+
+Or a custom class:
+
+```ruby
+class MyAddressCoercer
+  def call(value)
+    IPAddr.new(value)
+  end
+end
+
+class Server
+  include ValueSemantics.for_attributes {
+    address IPAddr, coerce: MyAddressCoercer.new
+  }
+end
+```
+
+Or reuse an existing class method:
+
+```ruby
+class Server
+  include ValueSemantics.for_attributes {
+    address IPAddr, coerce: IPAddr.method(:new)
+  }
+end
+```
 
 Coercion happens before validation.
+If coercion is not possible, coercers can return the raw value unchanged,
+allowing the validator to fail with a nice, descriptive exception.
+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.
 
 
 ## All Together
@@ -209,7 +249,7 @@ Default attribute values also pass through coercion.
 class Person
   include ValueSemantics.for_attributes {
     name String, default: "Anon Emous"
-    birthday Either(Date, nil)
+    birthday Either(Date, nil), coerce: true
   }
 
   def self.coerce_birthday(value)
@@ -231,7 +271,6 @@ Person.new(birthday: nil)
 #=> #<Person name="Anon Emous" birthday=nil>
 ```
 
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -249,6 +288,10 @@ Or install it yourself as:
     $ gem install value_semantics
 
 
+## TODO
+
+ - Allow defaults to be generated by calling a method (e.g. to get the current time)
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at:

data/lib/value_semantics.rb

@@ -75,19 +75,21 @@ module ValueSemantics
   end
 
   class Attribute
-    attr_reader :name, :has_default, :default_value, :validator
+    NOT_SPECIFIED = Object.new.freeze
 
-    def initialize(name:, has_default:, default_value:, validator:)
+    attr_reader :name, :validator, :coercer
+
+    def initialize(name:, default_value:, validator:, coercer:)
       @name = name.to_sym
-      @has_default = has_default
       @default_value = default_value
       @validator = validator
+      @coercer = coercer
       freeze
     end
 
     def determine_from!(attr_hash, klass)
       raw_value = attr_hash.fetch(name) do
-        if has_default
+        if default_specified?
           default_value
         else
           raise ArgumentError, "Value missing for attribute '#{name}'"
@@ -104,15 +106,21 @@ module ValueSemantics
     end
 
     def coerce(attr_value, klass)
-      if klass.respond_to?(coercion_method)
+      return attr_value unless coercer # coercion not enabled
+
+      if coercer.equal?(true)
         klass.public_send(coercion_method, attr_value)
       else
-        attr_value
+        coercer.call(attr_value)
       end
     end
 
+    def default_specified?
+      !@default_value.equal?(NOT_SPECIFIED)
+    end
+
     def default_value
-      if has_default
+      if default_specified?
         @default_value
       else
         fail "Attribute does not have a default value"
@@ -133,8 +141,6 @@ module ValueSemantics
   end
 
   class DSL
-    NOT_SPECIFIED = Object.new
-
     def self.run(&block)
       dsl = new
       dsl.instance_eval(&block)
@@ -163,12 +169,12 @@ module ValueSemantics
       ArrayOf.new(element_validator)
     end
 
-    def def_attr(attr_name, validator=Anything, default: NOT_SPECIFIED)
+    def def_attr(attr_name, validator=Anything, default: Attribute::NOT_SPECIFIED, coerce: nil)
       __attributes << Attribute.new(
         name: attr_name,
-        has_default: !(NOT_SPECIFIED.equal?(default)),
-        default_value: default,
         validator: validator,
+        default_value: default,
+        coercer: coerce
       )
     end
 

data/lib/value_semantics/version.rb

@@ -1,3 +1,3 @@
 module ValueSemantics
-  VERSION = "1.0.1"
+  VERSION = "2.0.1"
 end

metadata

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