coercive 1.1.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3eee84a8970b92e6b5d1b0e01e51a40c66cc0c7298b0fe37a6ea44aecd7b9064
-  data.tar.gz: 9504d35e8ce6376fd821110a15d079783f723af1ae78606fa7fd2e565c053487
+  metadata.gz: af1258f102aed9654f229199a6999f7dc817550b51fd009d9e8057de26c8cb11
+  data.tar.gz: 297d85ff20739bf100f7434d657a842adbaa783a17b10c459325724391d84196
 SHA512:
-  metadata.gz: 41fef05cb7a8c6a1d2f9b7f0f3737d76c5756a36903d6e2c45d028fb539d4de50f9ac0720b07e4262b97df2ff187638e0cf6d5fef4692d470ddc9484e00a9b57
-  data.tar.gz: 94c3e1e38e740c7089d8913977fbd1feea04d1df592d918c76b46be18c53787c95d36fed451a39191781db63718a941f31d53b4ac56d960384e1e854ed4d6066
+  metadata.gz: e9e1e6a9d98a32bc3819ef6ea4765f21a45ed103000186d71d394d10ac657178eb6498d55bebd2b7a54182cb6565593efc8f377f1ba8bf4074dbed030a81704f
+  data.tar.gz: 9cde425ae7847267b73118f741304a2a1b1b04cd7585d52c5d1bb0a5f51b664dd530c00a5e50c3bdecf9f0c0e3e3c1cc4a8a567a472e0d6745d28e26f84b76cb

data/README.md

@@ -128,6 +128,30 @@ CoerceFoo.call("foo" => "DEADBEEF")
 # => {"foo"=>"DEADBEEF"}
 ```
 
+### `date` and `datetime`
+
+The `date` and `datetime` coercion functions will receive a `String` and give you `Date` and `DateTime` objects, respectively.
+
+By default they expect an ISO 8601 string, but they provide a `format` option in case you need to parse something different, following the `strftime` format.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :date_foo,      date,                     optional
+  attribute :american_date, date(format: "%m-%d-%Y"), optional
+  attribute :datetime_foo,  datetime,                 optional
+end
+
+CoerceFoo.call("date_foo" => "1988-05-18", "datetime_foo" => "1988-05-18T21:00:00Z", "american_date" => "05-18-1988")
+# => {"date_foo"=>#<Date: 1988-05-18 ((2447300j,0s,0n),+0s,2299161j)>,
+#  "american_date"=>#<Date: 1988-05-18 ((2447300j,0s,0n),+0s,2299161j)>,
+#  "datetime_foo"=>#<DateTime: 1988-05-18T21:00:00+00:00 ((2447300j,75600s,0n),+0s,2299161j)>}
+
+CoerceFoo.call("date_foo" => "18th May 1988")
+# => Coercive::Error: {"date_foo"=>"not_valid"}
+```
+
 ### `any`
 
 The `any` coercion function lets anything pass through. It's commonly used with the `optional` fetch function when an attribute may or many not be a part of the input.
@@ -147,27 +171,90 @@ CoerceFoo.call("foo" => 4)
 # => Coercive::Error: {"foo"=>"not_valid"}
 ```
 
-### `float`
+### `integer(min:, max:)`
+
+`integer` expects an integer value. It supports optional `min` and `max` options to check if the user input is within certain bounds.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo,        integer,                  optional
+  attribute :foo_bounds, integer(min: 1, max: 10), optional
+end
+
+CoerceFoo.call("foo" => "1")
+# => {"foo"=>1}
+
+CoerceFoo.call("foo" => "bar")
+# => Coercive::Error: {"foo"=>"not_valid"}
+
+CoerceFoo.call("foo" => "1.5")
+# => Coercive::Error: {"foo"=>"not_numeric"}
+
+CoerceFoo.call("foo" => 1.5)
+# => Coercive::Error: {"foo"=>"float_not_permitted"}
+
+CoerceFoo.call("foo_bounds" => 0)
+# => Coercive::Error: {"foo_bounds"=>"too_low"}
+
+CoerceFoo.call("foo_bounds" => 11)
+# => Coercive::Error: {"foo_bounds"=>"too_high"}
+```
+
+### `float(min:, max:)`
 
-`float` expects, well, a float value.
+`float` expects, well, a float value. It supports optional `min` and `max` options to check if the user input is within certain bounds.
 
 ```ruby
 module CoerceFoo
   extend Coercive
 
-  attribute :foo, float, optional
+  attribute :foo,        float,                     optional
+  attribute :foo_bounds, float(min: 1.0, max: 5.5), optional
 end
 
 CoerceFoo.call("foo" => "bar")
 # => Coercive::Error: {"foo"=>"not_valid"}
 
+CoerceFoo.call("foo_bounds" => "0.5")
+# => Coercive::Error: {"foo_bounds"=>"too_low"}
+
+CoerceFoo.call("foo_bounds" => 6.5)
+# => Coercive::Error: {"foo_bounds"=>"too_high"}
+
 CoerceFoo.call("foo" => "0.1")
 # => {"foo"=>0.1}
-  
+
 CoerceFoo.call("foo" => "0.1e5")
 # => {"foo"=>10000.0}
 ```
 
+### `boolean(true_if:, false_if:)
+
+`boolean` will coerce input into `true` or `false`. You can also specifiy additional values to coerce into `true` or `false` with the `true_if` and `false_if` options.
+
+```ruby
+module CoerceFoo
+  extend Coercive
+
+  attribute :foo,    boolean,                               optional
+  attribute :foo_if, boolean(true_if: member(["1", "on"])), optional
+end
+
+CoerceFoo.call("foo" => true)
+# => {"foo"=>true}
+
+CoerceFoo.call("foo" => "true")
+# => {"foo"=>true}
+
+CoerceFoo.call("foo" => nil)
+# => Coercive::Error: {"foo"=>"not_valid"}
+
+CoerceFoo.call("foo_if" => "on")
+# => {"foo_if"=>true}
+```
+
 ### `array`
 
 The `array` coercion is interesting because it's where `Coercive` starts to shine, by letting you compose coercion functions together. Let's see:

data/coercive.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "coercive"
-  s.version = "1.1.0"
+  s.version = "1.6.0"
   s.summary = "Coercive is a library to validate and coerce user input"
   s.description = s.summary
   s.authors = ["Joe McIlvain", "Lucas Tolchinsky"]

data/lib/coercive.rb

@@ -1,3 +1,4 @@
+require "date"
 require_relative "coercive/uri"
 
 # Public: The Coercive module implements a succinct DSL for declaring callable
@@ -149,14 +150,65 @@ module Coercive
     end
   end
 
+  # Public DSL: Return a coerce function to coerce input to an Integer.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  def integer(min: nil, max: nil)
+    ->(input) do
+      fail Coercive::Error.new("float_not_permitted") if input.is_a?(Float)
+
+      input = begin
+                Integer(input)
+              rescue TypeError, ArgumentError
+                fail Coercive::Error.new("not_numeric")
+              end
+
+      fail Coercive::Error.new("too_low")  if min && input < min
+      fail Coercive::Error.new("too_high") if max && input > max
+
+      input
+    end
+  end
+
   # Public DSL: Return a coerce function to coerce input to a Float.
   # Used when declaring an attribute. See documentation for attr_coerce_fns.
-  def float
+  def float(min: nil, max: nil)
     ->(input) do
-      begin
-        Float(input)
-      rescue TypeError, ArgumentError
-        fail Coercive::Error.new("not_numeric")
+      input = begin
+                Float(input)
+              rescue TypeError, ArgumentError
+                fail Coercive::Error.new("not_numeric")
+              end
+
+      fail Coercive::Error.new("too_low")  if min && input < min
+      fail Coercive::Error.new("too_high") if max && input > max
+
+      input
+    end
+  end
+
+  # Public DSL: Return a coerce function to coerce input to true or false.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  #
+  # true_if  - coerce function to override which values will coerce to true.
+  # false_if - coerce function to override which values will coerce to false.
+  def boolean(true_if: member([true, "true"]), false_if: member([false, "false"]))
+    ->(input) do
+      test_success = ->(coerce_fn) do
+        begin
+          coerce_fn.call(input)
+        rescue Coercive::Error
+          return false
+        end
+
+        true
+      end
+
+      if test_success.(true_if)
+        true
+      elsif test_success.(false_if)
+        false
+      else
+        fail Coercive::Error.new("not_valid")
       end
     end
   end
@@ -192,6 +244,48 @@ module Coercive
     end
   end
 
+  # Public DSL: Return a coercion function to coerce input into a Date.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  #
+  # format - String following Ruby's `strftime` format to change the parsing behavior. When empty
+  #          it will expect the String to be ISO 8601 compatible.
+  def date(format: nil)
+    ->(input) do
+      input = begin
+                if format
+                  Date.strptime(input, format)
+                else
+                  Date.iso8601(input)
+                end
+              rescue ArgumentError
+                fail Coercive::Error.new("not_valid")
+              end
+
+      input
+    end
+  end
+
+  # Public DSL: Return a coercion function to coerce input into a DateTime.
+  # Used when declaring an attribute. See documentation for attr_coerce_fns.
+  #
+  # format - String following Ruby's `strftime` format to change the parsing behavior. When empty
+  #          it will expect the String to be ISO 8601 compatible.
+  def datetime(format: nil)
+    ->(input) do
+      input = begin
+                if format
+                  DateTime.strptime(input, format)
+                else
+                  DateTime.iso8601(input)
+                end
+              rescue ArgumentError
+                fail Coercive::Error.new("not_valid")
+              end
+
+      input
+    end
+  end
+
   # Public DSL: Return a coercion function to coerce input to an Array.
   # Used when declaring an attribute. See documentation for attr_coerce_fns.
   #

data/test/coercive.rb

@@ -100,12 +100,57 @@ describe "Coercive" do
     end
   end
 
+  describe "integer" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :foo, integer, optional
+        attribute :bar, integer, optional
+        attribute :baz, integer(min: 1, max: 10), optional
+      end
+    end
+
+    it "coerces the input value to an integer" do
+      attributes = { "foo" => "100", "bar" => 100 }
+
+      expected = { "foo" => 100, "bar" => 100 }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "doesn't allow Float" do
+      expected_errors = { "foo" => "float_not_permitted" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("foo" => 100.5) }
+    end
+
+    it "errors if the input can't be coerced into an Integer" do
+      ["nope", "100.5", "1e5"].each do |value|
+        expected_errors = { "foo" => "not_numeric" }
+
+        assert_coercion_error(expected_errors) { @coercion.call("foo" => value) }
+      end
+    end
+
+    it "errors if the input is out of bounds" do
+      expected_errors = { "baz" => "too_low" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("baz" => 0) }
+
+      expected_errors = { "baz" => "too_high" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("baz" => 11) }
+    end
+  end
+
   describe "float" do
     before do
       @coercion = Module.new do
         extend Coercive
 
-        attribute :foo, float, required
+        attribute :foo, float,                     optional
+        attribute :bar, float(min: 1.0, max: 5.5), optional
       end
     end
 
@@ -132,6 +177,74 @@ describe "Coercive" do
         assert_coercion_error(expected_errors) { @coercion.call("foo" => bad) }
       end
     end
+
+    it "errors if the input is out of bounds" do
+      expected_errors = { "bar" => "too_low" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("bar" => 0.5) }
+
+      expected_errors = { "bar" => "too_high" }
+
+      assert_coercion_error(expected_errors) { @coercion.call("bar" => 6.0) }
+    end
+  end
+
+  describe "boolean" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :foo,       boolean,                                 optional
+        attribute :foo_true,  boolean(true_if:  member(["on", 1])),    optional
+        attribute :foo_false, boolean(false_if: member(["off", "0"])), optional
+      end
+    end
+
+    it "supports true or false as String by default" do
+      [true, "true"].each do |value|
+        attributes = { "foo" => value }
+
+        expected = { "foo" => true }
+
+        assert_equal expected, @coercion.call(attributes)
+      end
+
+      [false, "false"].each do |value|
+        attributes = { "foo" => value }
+
+        expected = { "foo" => false }
+
+        assert_equal expected, @coercion.call(attributes)
+      end
+    end
+
+    it "supports customizing values to coerce into true or false" do
+      ["on", 1].each do |value|
+        attributes = { "foo_true" => value }
+
+        expected = { "foo_true" => true }
+
+        assert_equal expected, @coercion.call(attributes)
+      end
+
+      ["off", "0"].each do |value|
+        attributes = { "foo_false" => value }
+
+        expected = { "foo_false" => false }
+
+        assert_equal expected, @coercion.call(attributes)
+      end
+    end
+
+    it "fails on unknown values" do
+      ["nope", nil].each do |value|
+        attributes = { "foo" => value }
+
+        expected_errors = { "foo" => "not_valid" }
+        
+        assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+      end
+    end
   end
 
   describe "string" do
@@ -199,6 +312,84 @@ describe "Coercive" do
     end
   end
 
+  describe "date" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :date,          date,                     optional
+        attribute :american_date, date(format: "%m-%d-%Y"), optional
+      end
+    end
+
+    it "coerces a string into a Date object with ISO 8601 format by default" do
+      attributes = { "date" => "1988-05-18" }
+
+      expected = { "date" => Date.new(1988, 5, 18) }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "supports a custom date format" do
+      attributes = { "american_date" => "05-18-1988" }
+
+      expected = { "american_date" => Date.new(1988, 5, 18) }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "errors if the input doesn't parse" do
+      attributes = { "date" => "12-31-1990" }
+
+      expected_errors = { "date" => "not_valid" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+  end
+
+  describe "datetime" do
+    before do
+      @coercion = Module.new do
+        extend Coercive
+
+        attribute :datetime,      datetime,                                 optional
+        attribute :american_date, datetime(format: "%m-%d-%Y %I:%M:%S %p"), optional
+      end
+    end
+
+    it "coerces a string into a DateTime object with ISO 8601 format by default" do
+      attributes = { "datetime" => "1988-05-18T21:00:00Z" }
+
+      expected = { "datetime" => DateTime.new(1988, 5, 18, 21, 00, 00) }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "honors the timezone" do
+      attributes = { "datetime" => "1988-05-18T21:00:00-0300" }
+
+      expected = { "datetime" => DateTime.new(1988, 5, 18, 21, 00, 00, "-03:00") }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "supports a custom date format" do
+      attributes = { "american_date" => "05-18-1988 09:00:00 PM" }
+
+      expected = { "american_date" => DateTime.new(1988, 5, 18, 21, 00, 00) }
+
+      assert_equal expected, @coercion.call(attributes)
+    end
+
+    it "errors if the input doesn't parse" do
+      attributes = { "datetime" => "12-31-1990T21:00:00Z" }
+
+      expected_errors = { "datetime" => "not_valid" }
+
+      assert_coercion_error(expected_errors) { @coercion.call(attributes) }
+    end
+  end
+
   describe "array" do
     before do
       @coercion = Module.new do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coercive
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Joe McIlvain
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-13 00:00:00.000000000 Z
+date: 2020-09-21 00:00:00.000000000 Z
 dependencies: []
 description: Coercive is a library to validate and coerce user input
 email: