entitlements 0.1.8 → 0.2.0

data/lib/contracts-ruby2/features/basics/pretty-print.feature

@@ -0,0 +1,241 @@
+Feature: Pretty printing Contract violations
+
+  Scenario: Big array argument being passed to big array method parameter
+    Given a file named "example.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      class << self
+        Contract [
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol]
+        ] => nil
+        def run(data)
+          nil
+        end
+      end
+    end
+
+    puts Example.run([
+      ["foo", "foo"],
+      ["foo", "foo"],
+      ["foo", "foo"],
+      ["foo", "foo"],
+      ["foo", "foo"],
+      ["foo", "foo"],
+      ["foo", "foo"],
+      ["foo", "foo"],
+      ["foo", "foo"]
+    ])
+    """
+    When I run `ruby example.rb`
+    Then the output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: [(String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol)],
+            Actual: [["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"]]
+            Value guarded in: Example::run
+            With Contract: Array => NilClass
+            At: example.rb:17
+    """
+
+  Scenario: Big array value being returned from method expecting different big array type
+    Given a file named "example.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      class << self
+        Contract C::None => [
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol],
+            C::Or[String, Symbol]
+        ]
+        def run
+          [
+            ["foo", "foo"],
+            ["foo", "foo"],
+            ["foo", "foo"],
+            ["foo", "foo"],
+            ["foo", "foo"],
+            ["foo", "foo"],
+            ["foo", "foo"],
+            ["foo", "foo"],
+            ["foo", "foo"]
+          ]
+        end
+      end
+    end
+
+    puts Example.run
+    """
+    When I run `ruby example.rb`
+    Then the output should contain:
+    """
+    : Contract violation for return value: (ReturnContractError)
+            Expected: [(String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol),
+                       (String or Symbol)],
+            Actual: [["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"],
+                     ["foo", "foo"]]
+            Value guarded in: Example::run
+            With Contract: None => Array
+            At: example.rb:17
+    """
+
+  Scenario: Big hash argument being passed to big hash method parameter
+    Given a file named "example.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      class << self
+        Contract ({
+            a: C::Or[String, Symbol],
+            b: C::Or[String, Symbol],
+            c: C::Or[String, Symbol],
+            d: C::Or[String, Symbol],
+            e: C::Or[String, Symbol],
+            f: C::Or[String, Symbol],
+            g: C::Or[String, Symbol]
+        }) => nil
+        def run(data)
+          nil
+        end
+      end
+    end
+
+    puts Example.run({
+      a: ["foo", "foo"],
+      b: ["foo", "foo"],
+      c: ["foo", "foo"],
+      d: ["foo", "foo"],
+      e: ["foo", "foo"],
+      f: ["foo", "foo"],
+      g: ["foo", "foo"]
+    })
+    """
+    When I run `ruby example.rb`
+    Then the output should contain:
+    """
+    : Contract violation for argument 1 of 1: (ParamContractError)
+            Expected: {:a=>(String or Symbol),
+                       :b=>(String or Symbol),
+                       :c=>(String or Symbol),
+                       :d=>(String or Symbol),
+                       :e=>(String or Symbol),
+                       :f=>(String or Symbol),
+                       :g=>(String or Symbol)},
+            Actual: {:a=>["foo", "foo"],
+                     :b=>["foo", "foo"],
+                     :c=>["foo", "foo"],
+                     :d=>["foo", "foo"],
+                     :e=>["foo", "foo"],
+                     :f=>["foo", "foo"],
+                     :g=>["foo", "foo"]}
+            Value guarded in: Example::run
+            With Contract: Hash => NilClass
+            At: example.rb:17
+    """
+
+  Scenario: Big hash value being returned from method expecting different big hash type
+    Given a file named "example.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      class << self
+        Contract C::None => ({
+            a: C::Or[String, Symbol],
+            b: C::Or[String, Symbol],
+            c: C::Or[String, Symbol],
+            d: C::Or[String, Symbol],
+            e: C::Or[String, Symbol],
+            f: C::Or[String, Symbol],
+            g: C::Or[String, Symbol]
+        })
+        def run
+          {
+            a: ["foo", "foo"],
+            b: ["foo", "foo"],
+            c: ["foo", "foo"],
+            d: ["foo", "foo"],
+            e: ["foo", "foo"],
+            f: ["foo", "foo"],
+            g: ["foo", "foo"]
+          }
+        end
+      end
+    end
+
+    puts Example.run
+    """
+    When I run `ruby example.rb`
+    Then the output should contain:
+    """
+    : Contract violation for return value: (ReturnContractError)
+            Expected: {:a=>(String or Symbol),
+                       :b=>(String or Symbol),
+                       :c=>(String or Symbol),
+                       :d=>(String or Symbol),
+                       :e=>(String or Symbol),
+                       :f=>(String or Symbol),
+                       :g=>(String or Symbol)},
+            Actual: {:a=>["foo", "foo"],
+                     :b=>["foo", "foo"],
+                     :c=>["foo", "foo"],
+                     :d=>["foo", "foo"],
+                     :e=>["foo", "foo"],
+                     :f=>["foo", "foo"],
+                     :g=>["foo", "foo"]}
+            Value guarded in: Example::run
+            With Contract: None => Hash
+            At: example.rb:17
+    """

data/lib/contracts-ruby2/features/basics/simple_example.feature

@@ -0,0 +1,210 @@
+Feature: Simple examples and Contract violations
+
+  Contracts.ruby allows specification of contracts on per-method basis, where
+  method arguments and return value will be validated upon method call.
+
+  Example:
+
+  ```ruby
+  Contract C::Num, C::Num => C::Num
+  def add(a, b)
+    a + b
+  end
+  ```
+
+  Here `Contract arg_contracts... => return_contract` defines list of argument
+  contracts `args_contracts...` as `C::Num, C::Num` (i.e.: both arguments
+  should be numbers) and return value contract `return_contract` as `C::Num`
+  (i.e.: return value should be a number too).
+
+  `Contract arg_contracts... => return_contract` affects next defined instance,
+  class or singleton method, meaning that all of these work:
+
+  - [Instance method](#instance-method),
+
+  - [Class method](#class-method),
+
+  - [Singleton method](#singleton-method).
+
+  Whenever invalid argument is passed to a contracted method, corresponding
+  `ContractError` will be raised. That happens right after bad value got into
+  system protected by contracts and prevents error propagation: first
+  non-contracts library frame in exception's backtrace is a culprit for passing
+  an invalid argument - you do not need to verify 20-30 frames to find a
+  culprit! Example of such error: [instance method contract
+  violation](#instance-method-contract-violation).
+
+  Whenever invalid return value is returned from a contracted method,
+  corresponding `ContractError` will be raised. That happens right after method
+  returned this value and prevents error propagation: `At: your_filename.rb:17`
+  part of error message points directly to a culprit method. Example of such
+  error: [return value contract
+  violation](#singleton-method-return-value-contract-violation).
+
+  Contract violation error consists of such parts:
+  - Violation type:
+    - `Contract violation for argument X of Y: (ParamContractError)`,
+    - `Contract violation for return value (ReturnContractError)`.
+  - Expected contract, example: `Expected: Num`.
+  - Actual value, example: `Actual: "foo"`.
+  - Location of violated contract, example: `Value guarded in: Example::add`.
+  - Full contract, example: `With Contract: Num, Num => Num`.
+  - Source code location of contracted method, example: `At: lib/your_library/some_class.rb:17`.
+
+  Scenario: Instance method
+    Given a file named "instance_method.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      Contract C::Num, C::Num => C::Num
+      def add(a, b)
+        a + b
+      end
+    end
+
+    puts Example.new.add(2, 2)
+    """
+    When I run `ruby instance_method.rb`
+    Then the output should contain:
+    """
+    4
+    """
+
+  Scenario: Instance method contract violation
+    Given a file named "instance_method_violation.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      Contract C::Num, C::Num => C::Num
+      def add(a, b)
+        a + b
+      end
+    end
+
+    puts Example.new.add(2, "foo")
+    """
+    When I run `ruby instance_method_violation.rb`
+    Then the output should contain:
+    """
+    : Contract violation for argument 2 of 2: (ParamContractError)
+            Expected: Num,
+            Actual: "foo"
+            Value guarded in: Example::add
+            With Contract: Num, Num => Num
+            At: instance_method_violation.rb:8
+    """
+
+  Scenario: Class method
+    Given a file named "class_method.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      Contract C::Num, C::Num => C::Num
+      def self.add(a, b)
+        a + b
+      end
+    end
+
+    puts Example.add(2, 2)
+    """
+    When I run `ruby class_method.rb`
+    Then the output should contain:
+    """
+    4
+    """
+
+  Scenario: Class method contract violation
+    Given a file named "class_method_violation.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      Contract C::Num, C::Num => C::Num
+      def self.add(a, b)
+        a + b
+      end
+    end
+
+    puts Example.add(:foo, 2)
+    """
+    When I run `ruby class_method_violation.rb`
+    Then the output should contain:
+    """
+    : Contract violation for argument 1 of 2: (ParamContractError)
+            Expected: Num,
+            Actual: :foo
+            Value guarded in: Example::add
+            With Contract: Num, Num => Num
+            At: class_method_violation.rb:8
+    """
+
+  Scenario: Singleton method
+    Given a file named "singleton_method.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      class << self
+        Contract C::Num, C::Num => C::Num
+        def add(a, b)
+          a + b
+        end
+      end
+    end
+
+    puts Example.add(2, 2)
+    """
+    When I run `ruby singleton_method.rb`
+    Then the output should contain:
+    """
+    4
+    """
+
+  Scenario: Singleton method return value contract violation
+    Given a file named "singleton_method_violation.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      class << self
+        Contract C::Num, C::Num => C::Num
+        def add(a, b)
+          # notice here non-number is returned
+          nil
+        end
+      end
+    end
+
+    puts Example.add(2, 2)
+    """
+    When I run `ruby singleton_method_violation.rb`
+    Then the output should contain:
+    """
+    : Contract violation for return value: (ReturnContractError)
+            Expected: Num,
+            Actual: nil
+            Value guarded in: Example::add
+            With Contract: Num, Num => Num
+            At: singleton_method_violation.rb:9
+    """

data/lib/contracts-ruby2/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/lib/contracts-ruby2/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/lib/contracts-ruby2/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/lib/contracts-ruby2/features/builtin_contracts/args.feature

@@ -0,0 +1,80 @@
+Feature: Args
+
+  Used for `*args` (variadic functions). Takes contract and uses it to validate
+  every element passed in through `*args`.
+
+  ```ruby
+  Contract C::Args[C::Num] => C::Bool
+  def example(*args)
+  ```
+
+  This example contract will validate all arguments passed through `*args` to
+  accept only numbers.
+
+  Background:
+    Given a file named "args_usage.rb" with:
+    """ruby
+    require "contracts"
+    C = Contracts
+
+    class Example
+      include Contracts::Core
+
+      Contract C::Args[C::Num] => C::Bool
+      def only_nums(*args)
+        args.inspect
+      end
+    end
+    """
+
+  Scenario: Accepts no arguments
+    Given a file named "accepts_no_arguments.rb" with:
+    """ruby
+    require "./args_usage"
+    puts Example.new.only_nums
+    """
+    When I run `ruby accepts_no_arguments.rb`
+    Then the output should contain:
+    """
+    []
+    """
+
+  Scenario: Accepts one valid argument
+    Given a file named "accepts_one_argument.rb" with:
+    """ruby
+    require "./args_usage"
+    puts Example.new.only_nums(42)
+    """
+    When I run `ruby accepts_one_argument.rb`
+    Then the output should contain:
+    """
+    [42]
+    """
+
+  Scenario: Accepts many valid arguments
+    Given a file named "accepts_many_arguments.rb" with:
+    """ruby
+    require "./args_usage"
+    puts Example.new.only_nums(42, 45, 17, 24)
+    """
+    When I run `ruby accepts_many_arguments.rb`
+    Then the output should contain:
+    """
+    [42, 45, 17, 24]
+    """
+
+  Scenario: Rejects invalid argument
+    Given a file named "rejects_invalid_argument.rb" with:
+    """ruby
+    require "./args_usage"
+    puts Example.new.only_nums(42, "foo", 17, 24)
+    """
+    When I run `ruby rejects_invalid_argument.rb`
+    Then the output should contain:
+    """
+    : Contract violation for argument 1 of 4: (ParamContractError)
+            Expected: (Args[Contracts::Builtin::Num]),
+            Actual: "foo"
+            Value guarded in: Example::only_nums
+            With Contract: Args => Bool
+    """

data/lib/contracts-ruby2/features/builtin_contracts/array_of.feature

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