contracts 0.11.0 → 0.12.0

data/features/builtin_contracts/README.md

@@ -0,0 +1,22 @@
+To use builtin contracts you can refer them with `Contracts::*`:
+
+```ruby
+Contract Contracts::Num => Contracts::Maybe(Contracts::Num)
+```
+
+It is recommended to use a short alias for `Contracts`, for example `C`:
+
+```ruby
+C = Contracts
+
+Contract C::Num => C::Maybe(C::Num)
+```
+
+It is possible to `include Contracts` and refer them without namespace, but
+this is deprecated and not recommended.
+
+*NOTE: in the future it will be possible to do `include Contracts::Builtin`
+instead.*
+
+*NOTE: all contracts marked as (TODO) have their documentaion `.feature` file
+as stub. Contributions to those are warmly welcome!*

data/features/builtin_contracts/and.feature

@@ -0,0 +1,103 @@
+Feature: And
+
+  Takes a variable number of contracts. The contract passes if all of the
+  contracts pass.
+
+  ```ruby
+  Contract C::And[Float, C::Neg] => String
+  ```
+
+  This example will validate first argument of a method and accept only
+  negative `Float`.
+
+  Background:
+    Given a file named "and_usage.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      Contract C::And[Float, C::Neg] => String
+      def fneg_string(number)
+        number.to_i.to_s
+      end
+    end
+    """
+
+  Scenario: Accepts negative float
+    Given a file named "accepts_negative_float.rb" with:
+    """ruby
+    require "./and_usage"
+    puts Example.new.fneg_string(-3.7)
+    """
+    When I run `ruby accepts_negative_float.rb`
+    Then output should contain:
+    """
+    -3
+    """
+
+  Scenario: Rejects positive float
+    Given a file named "rejects_positive_float.rb" with:
+    """ruby
+    require "./and_usage"
+    puts Example.new.fneg_string(7.5)
+    """
+    When I run `ruby rejects_positive_float.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: (Float and Neg),
+            Actual: 7.5
+            Value guarded in: Example::fneg_string
+            With Contract: And => String
+    """
+
+  Scenario: Rejects negative integer
+    Given a file named "rejects_negative_integer.rb" with:
+    """ruby
+    require "./and_usage"
+    puts Example.new.fneg_string(-5)
+    """
+    When I run `ruby rejects_negative_integer.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: (Float and Neg),
+            Actual: -5
+            Value guarded in: Example::fneg_string
+            With Contract: And => String
+    """
+
+  Scenario: Rejects positive integer
+    Given a file named "rejects_positive_integer.rb" with:
+    """ruby
+    require "./and_usage"
+    puts Example.new.fneg_string(5)
+    """
+    When I run `ruby rejects_positive_integer.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: (Float and Neg),
+            Actual: 5
+            Value guarded in: Example::fneg_string
+            With Contract: And => String
+    """
+
+  Scenario: Rejects others
+    Given a file named "rejects_others.rb" with:
+    """ruby
+    require "./and_usage"
+    puts Example.new.fneg_string(:foo)
+    """
+    When I run `ruby rejects_others.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: (Float and Neg),
+            Actual: :foo
+            Value guarded in: Example::fneg_string
+            With Contract: And => String
+    """

data/features/builtin_contracts/any.feature

@@ -0,0 +1,44 @@
+Feature: Any
+
+  Passes for any argument.
+
+  ```ruby
+  Contract C::Any => String
+  ```
+
+  Scenario: Accepts any argument
+    Given a file named "any_usage.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      Contract C::Any => String
+      def self.stringify(x)
+        x.inspect
+      end
+    end
+
+    puts Example.stringify(25)
+    puts Example.stringify(37.59)
+    puts Example.stringify("foo")
+    puts Example.stringify(:foo)
+    puts Example.stringify(nil)
+    puts Example.stringify(Object)
+    """
+    When I run `ruby any_usage.rb`
+    Then output should contain:
+    """
+    25
+    37.59
+    "foo"
+    :foo
+    nil
+    Object
+    """
+    And output should not contain:
+    """
+    Contract violation for
+    """

data/features/builtin_contracts/args.feature

@@ -0,0 +1 @@
+Feature: Args (TODO)

data/features/builtin_contracts/array_of.feature

@@ -0,0 +1 @@
+Feature: ArrayOf (TODO)

data/features/builtin_contracts/bool.feature

@@ -0,0 +1,64 @@
+Feature: Bool
+
+  Checks that the argument is a `true` or `false`.
+
+  ```ruby
+  Contract String => C::Bool
+  ```
+
+  Background:
+    Given a file named "bool_usage.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      Contract String => C::Bool
+      def self.strong?(password)
+        return if password == ""
+        password.length > 22
+      end
+    end
+    """
+
+  Scenario: Accepts `true`
+    Given a file named "true.rb" with:
+    """ruby
+    require "./bool_usage"
+    puts Example.strong?("verystrongandLon774gPassword!ForYouHere")
+    """
+    When I run `ruby true.rb`
+    Then output should contain:
+    """
+    true
+    """
+
+  Scenario: Accepts `false`
+    Given a file named "false.rb" with:
+    """ruby
+    require "./bool_usage"
+    puts Example.strong?("welcome")
+    """
+    When I run `ruby false.rb`
+    Then output should contain:
+    """
+    false
+    """
+
+  Scenario: Rejects everything else
+    Given a file named "nil.rb" with:
+    """ruby
+    require "./bool_usage"
+    puts Example.strong?("")
+    """
+    When I run `ruby nil.rb`
+    Then output should contain:
+    """
+    : Contract violation for return value: (ReturnContractError)
+            Expected: Bool,
+            Actual: nil
+            Value guarded in: Example::strong?
+            With Contract: String => Bool
+    """

data/features/builtin_contracts/enum.feature

@@ -0,0 +1 @@
+Feature: Enum (TODO)

data/features/builtin_contracts/eq.feature

@@ -0,0 +1 @@
+Feature: Eq (TODO)

data/features/builtin_contracts/exactly.feature

@@ -0,0 +1 @@
+Feature: Exactly (TODO)

data/features/builtin_contracts/func.feature

@@ -0,0 +1 @@
+Feature: Func (TODO)

data/features/builtin_contracts/hash_of.feature

@@ -0,0 +1 @@
+Feature: HashOf (TODO)

data/features/builtin_contracts/keyword_args.feature

@@ -0,0 +1 @@
+Feature: KeywordArgs (TODO)

data/features/builtin_contracts/maybe.feature

@@ -0,0 +1 @@
+Feature: Maybe (TODO)

data/features/builtin_contracts/nat.feature

@@ -0,0 +1,115 @@
+Feature: Nat
+
+  Checks that an argument is a natural number.
+
+  ```ruby
+  Contract C::Nat => C::Nat
+  ```
+
+  Background:
+    Given a file named "nat_usage.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Natural
+      include Contracts::Core
+
+      Contract C::Nat => C::Nat
+      def prev(number)
+        number - 1
+      end
+    end
+    """
+
+  Scenario: Accepts positive integers
+    Given a file named "accepts_positive_integers.rb" with:
+    """ruby
+    require "./nat_usage"
+    puts Natural.new.prev(7)
+    """
+    When I run `ruby accepts_positive_integers.rb`
+    Then output should contain:
+    """
+    6
+    """
+
+  Scenario: Accepts zero
+    Given a file named "accepts_zero.rb" with:
+    """ruby
+    require "./nat_usage"
+    puts Natural.new.prev(1)
+    """
+    When I run `ruby accepts_zero.rb`
+    Then output should contain:
+    """
+    0
+    """
+
+  Scenario: Rejects negative integers
+    Given a file named "rejects_negative_integers.rb" with:
+    """ruby
+    require "./nat_usage"
+    puts Natural.new.prev(-1)
+    """
+    When I run `ruby rejects_negative_integers.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: Nat,
+            Actual: -1
+            Value guarded in: Natural::prev
+            With Contract: Nat => Nat
+    """
+    And output should contain "nat_usage.rb:8"
+
+  Scenario: Rejects negative integers as a return value
+    Given a file named "rejects_negative_integers.rb" with:
+    """ruby
+    require "./nat_usage"
+    puts Natural.new.prev(0)
+    """
+    When I run `ruby rejects_negative_integers.rb`
+    Then output should contain:
+    """
+    : Contract violation for return value: (ReturnContractError)
+            Expected: Nat,
+            Actual: -1
+            Value guarded in: Natural::prev
+            With Contract: Nat => Nat
+    """
+    And output should contain "nat_usage.rb:8"
+
+  Scenario: Rejects floats
+    Given a file named "rejects_floats.rb" with:
+    """ruby
+    require "./nat_usage"
+    puts Natural.new.prev(3.43)
+    """
+    When I run `ruby rejects_floats.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: Nat,
+            Actual: 3.43
+            Value guarded in: Natural::prev
+            With Contract: Nat => Nat
+    """
+    And output should contain "nat_usage.rb:8"
+
+  Scenario: Rejects other values
+    Given a file named "rejects_others.rb" with:
+    """ruby
+    require "./nat_usage"
+    puts Natural.new.prev("foo")
+    """
+    When I run `ruby rejects_others.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: Nat,
+            Actual: "foo"
+            Value guarded in: Natural::prev
+            With Contract: Nat => Nat
+    """
+    And output should contain "nat_usage.rb:8"

data/features/builtin_contracts/neg.feature

@@ -0,0 +1,115 @@
+Feature: Neg
+
+  Checks that an argument is negative `Numeric`.
+
+  ```ruby
+  Contract C::Neg => C::Neg
+  ```
+
+  Background:
+    Given a file named "pos_usage.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      Contract C::Neg => C::Neg
+      def double_expense(amount)
+        amount * 2
+      end
+    end
+    """
+
+  Scenario: Accepts negative integers
+    Given a file named "accepts_negative_integers.rb" with:
+    """ruby
+    require "./pos_usage"
+    puts Example.new.double_expense(-50)
+    """
+    When I run `ruby accepts_negative_integers.rb`
+    Then output should contain:
+    """
+    -100
+    """
+
+  Scenario: Accepts negative floats
+    Given a file named "accepts_negative_floats.rb" with:
+    """ruby
+    require "./pos_usage"
+    puts Example.new.double_expense(-37.99)
+    """
+    When I run `ruby accepts_negative_floats.rb`
+    Then output should contain:
+    """
+    -75.98
+    """
+
+  Scenario: Rejects positive integers
+    Given a file named "rejects_positive_integers.rb" with:
+    """ruby
+    require "./pos_usage"
+    puts Example.new.double_expense(50)
+    """
+    When I run `ruby rejects_positive_integers.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: Neg,
+            Actual: 50
+            Value guarded in: Example::double_expense
+            With Contract: Neg => Neg
+    """
+    And output should contain "pos_usage.rb:8"
+
+  Scenario: Rejects positive floats
+    Given a file named "rejects_positive_floats.rb" with:
+    """ruby
+    require "./pos_usage"
+    puts Example.new.double_expense(42.50)
+    """
+    When I run `ruby rejects_positive_floats.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: Neg,
+            Actual: 42.5
+            Value guarded in: Example::double_expense
+            With Contract: Neg => Neg
+    """
+    And output should contain "pos_usage.rb:8"
+
+  Scenario: Rejects zero
+    Given a file named "rejects_zero.rb" with:
+    """ruby
+    require "./pos_usage"
+    puts Example.new.double_expense(0)
+    """
+    When I run `ruby rejects_zero.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: Neg,
+            Actual: 0
+            Value guarded in: Example::double_expense
+            With Contract: Neg => Neg
+    """
+    And output should contain "pos_usage.rb:8"
+
+  Scenario: Rejects other values
+    Given a file named "rejects_others.rb" with:
+    """ruby
+    require "./pos_usage"
+    puts Example.new.double_expense("foo")
+    """
+    When I run `ruby rejects_others.rb`
+    Then output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: Neg,
+            Actual: "foo"
+            Value guarded in: Example::double_expense
+            With Contract: Neg => Neg
+    """
+    And output should contain "pos_usage.rb:8"