contracts 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 588796ed6d26a1394810a86debd6f0b285dfb7e1
-  data.tar.gz: bff5d90964ae5bb9911b66236c5898ad741c159b
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MzAzMDEzNDY4MjVjYWM2Njk2ZWViYTI0MTQ4MTI5ZGZiMGZhOTNhNA==
+  data.tar.gz: !binary |-
+    NDFhYTJmODVkY2FlNWE3ZGI2ZjcxM2JiODMyODBlZjM4MmRjZDkwZQ==
 SHA512:
-  metadata.gz: 678e7911e3dee12d273a8839712583bd0cc1272bde6da8aa8bdc27685751a66c9c9a25c39b1182c6056ff1d8bce191b8982783a18abadeff2526501040f61133
-  data.tar.gz: 5c8b7cd54ebff1b8d9d75393a2c1f0d45df096c295c3387eefd54a1a01695afe8fe1ef4975bc09705d1a6d081761fe42ffb8512d926df6cc0104e10f764844c6
+  metadata.gz: !binary |-
+    ZjNmODA2MDM5NGI0MjVjMzI0MDNlYmRjZWMzOTUxNmFhYmE0NWU1OGIwNzEz
+    ZDAwMmNhZWVkMTMxMDZkZTUwOGMwN2VhYjBlOTg2MGFhNmEzNjM1N2Q0NTJi
+    YzMzN2Y1ZTBiMWIwZDgyYWM0MmM5N2IyMjQ3ZWVmZGMwYzQxZDE=
+  data.tar.gz: !binary |-
+    ZTI2OWM5ZTNmYjFmMTI1NjU5ODUwNzM4MTg3NDBjYjkxM2RkZDJiYTBjNTcy
+    ZGY4NzYzZWU2NmM3Njc2ZmFlZjAzYzBkZDdhYTQ3ZmViNDYyMDY5Yzc2N2M3
+    Y2U5NTczYjdiODZjZjAxMzNiOGVjYTkyNzlhY2UyYmM3NDQzOWQ=

data/CHANGELOG.markdown

@@ -1,4 +1,12 @@
+## v0.12.0
+
+- Feature: add `Regexp` validator - [Gert Goet](https://github.com/eval) [#196](https://github.com/egonSchiele/contracts.ruby/pull/196)
+- Docs: bootstrap cucumber/aruba/relish setup - [Oleksii Fedorov](https://github.com/waterlink) [#195](https://github.com/egonSchiele/contracts.ruby/pull/195)
+- Bugfix: allow to `extend` module, that has `Contracts` or `Contracts::Core` included without harming current module/class `Contracts` functionality, see: [#176](https://github.com/egonSchiele/contracts.ruby/issues/176) - [Oleksii Fedorov](https://github.com/waterlink) [#198](https://github.com/egonSchiele/contracts.ruby/pull/198)
+- Enhancement: add `include Contracts::Builtin` to allow users to use builtin contracts without `Contracts::` prefix together with `include Contracts::Core` - [PikachuEXE](https://github.com/PikachuEXE) [#199](https://github.com/egonSchiele/contracts.ruby/pull/199)
+
 ## v0.11.0
+
 - Enhancement: add `include Contracts::Core` that doesn't pollute the namespace as much as `include Contracts` - [Oleksii Federov](https://github.com/waterlink) [#185](https://github.com/egonSchiele/contracts.ruby/pull/185)
 - Bugfix: fail if a non-hash is provided to a `HashOf` contract - [Abe Voelker](https://github.com/abevoelker) [#190](https://github.com/egonSchiele/contracts.ruby/pull/190)
 - Bugfix: bugfix for using varargs and `Maybe[Proc]` together - [Adit Bhargava](https://github.com/egonSchiele) [#188](https://github.com/egonSchiele/contracts.ruby/pull/188)

data/Gemfile

@@ -4,10 +4,13 @@ gemspec
 
 group :test do
   gem "rspec"
+  gem "aruba"
+  gem "cucumber", "~> 1.3.20"
   gem "rubocop", "~> 0.29.1", :platform => [:ruby_20, :ruby_21, :ruby_22]
 end
 
 group :development do
+  gem "relish"
   gem "method_profiler"
   gem "ruby-prof"
   gem "rake"

data/README.md

@@ -23,24 +23,28 @@ This says that double expects a number and returns a number. Here's the full cod
 
 ```ruby
 require 'contracts'
-include Contracts
 
-Contract Num => Num
-def double(x)
-  x * 2
+class Example
+  include Contracts::Core
+  include Contracts::Builtin
+
+  Contract Num => Num
+  def double(x)
+    x * 2
+  end
 end
 
-puts double("oops")
+puts Example.new.double("oops")
 ```
 
 Save this in a file and run it. Notice we are calling `double` with `"oops"`, which is not a number. The contract fails with a detailed error message:
 
-    ./contracts.rb:34:in `failure_callback': Contract violation: (RuntimeError)
-        Expected: Contracts::Num,
+ParamContractError: Contract violation for argument 1 of 1:
+        Expected: Num,
         Actual: "oops"
-        Value guarded in: Object::double
-        With Contract: Contracts::Num, Contracts::Num
-        At: main.rb:6
+        Value guarded in: Example::double
+        With Contract: Num => Num
+        At: main.rb:8
         ...stack trace...
 
 Instead of throwing an exception, you could log it, print a clean error message for your user...whatever you want. contracts.ruby is here to help you handle bugs better, not to get in your way.

data/TUTORIAL.md

@@ -63,7 +63,7 @@ This can be useful if you're in a REPL and want to figure out how a function sho
 
 ## Built-in Contracts
 
-`Num` is one of the built-in contracts that contracts.ruby comes with. The built-in contracts are in the `Contracts` namespace. The easiest way to use them is to include the `Contracts` module in your class/module.
+`Num` is one of the built-in contracts that contracts.ruby comes with. The built-in contracts are in the `Contracts` namespace. The easiest way to use them is to include the `Contracts::Builtin` module in your class/module.
 
 contracts.ruby comes with a lot of built-in contracts, including the following:
 
@@ -120,6 +120,22 @@ with while typing and anything that does not conflict with libraries you use.
 
 All examples after this point assume you have chosen a shortcut as `C::`.
 
+If you are sure, that builtin contracts will not nameclash with your own code
+and libraries you may use, then you can include all builtin contracts in your
+class/module:
+
+```ruby
+class Example
+  include Contracts::Core
+  include Contracts::Builtin
+
+  Contract Maybe[Num], Or[Float, String] => Bool
+  def complicated_algorithm(a, b)
+    # ...
+  end
+end
+```
+
 ## More Examples
 
 ### Hello, World
@@ -271,6 +287,22 @@ give_largest_value(a: 1, b: 2, c: 3) # returns 3
 give_largest_value("a" => 1, 2 => 2, c: 3)
 ```
 
+### Contracts On Strings
+
+When you want a contract to match not just any string (i.e. `Contract String => nil`), you can use regular expressions:
+```ruby
+Contract /World|Mars/i => nil
+def greet(name)
+  puts "Hello #{name}!"
+end
+```
+
+Using logical combinations you can combine existing definitions, instead of writing 1 big regular expression:
+```ruby
+Contract C::And[default_mail_regexp, /#{AppConfig.domain}\z/] => nil
+def send_admin_invite(email)
+```
+
 ### Contracts On Keyword Arguments
 
 ruby 2.0+, but can be used for normal hashes too, when keyword arguments are
@@ -562,6 +594,7 @@ Possible validator overrides:
 - `override_validator(Array)` - e.g. `[C::Num, String]`,
 - `override_validator(Hash)` - e.g. `{ :a => C::Num, :b => String }`,
 - `override_validator(Range)` - e.g. `(1..10)`,
+- `override_validator(Regexp)` - e.g. `/foo/`,
 - `override_validator(Contracts::Args)` - e.g. `C::Args[C::Num]`,
 - `override_validator(Contracts::Func)` - e.g. `C::Func[C::Num => C::Num]`,
 - `override_validator(:valid)` - allows to override how contracts that respond to `:valid?` are handled,

data/benchmarks/io.rb

@@ -8,15 +8,15 @@ require "open-uri"
 include Contracts
 
 def download url
-  open("https://www.#{url}/").read
+  open("http://www.#{url}/").read
 end
 
 Contract String => String
 def contracts_download url
-  open("https://www.#{url}").read
+  open("http://www.#{url}").read
 end
 
-@urls = %w{facebook.com google.com bing.com}
+@urls = %w{google.com bing.com}
 
 def benchmark
   Benchmark.bm 30 do |x|

data/cucumber.yml

@@ -0,0 +1 @@
+default: --require features

data/features/README.md

@@ -0,0 +1,17 @@
+contracts.ruby brings code contracts to the Ruby language.
+
+Example:
+
+```ruby
+class Example
+  include Contracts::Core
+  C = Contracts
+
+  Contract C::Num, C::Num => C::Num
+  def add(a, b)
+    a + b
+  end
+end
+```
+
+This documentation is [open source](https://github.com/egonSchiele/contracts.ruby/tree/master/features). If you find it incomplete or confusing, please [submit an issue](https://github.com/egonSchiele/contracts.ruby/issues), or, better yet, [a pull request](https://github.com/egonSchiele/contracts.ruby).

data/features/basics/functype.feature

@@ -0,0 +1,71 @@
+Feature: Fetching contracted function type
+
+  You can use `functype(name)` method for that:
+
+  ```ruby
+  functype(:add) # => "add :: Num, Num => Num"
+  ```
+
+  Background:
+    Given a file named "example.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
+
+      Contract String => String
+      def self.greeting(name)
+        "Hello, #{name}"
+      end
+
+      class << self
+        Contract C::Num => C::Num
+        def increment(number)
+          number + 1
+        end
+      end
+    end
+    """
+
+  Scenario: functype on instance method
+    Given a file named "instance_method_functype.rb" with:
+    """ruby
+    require "./example"
+    puts Example.new.functype(:add)
+    """
+    When I run `ruby instance_method_functype.rb`
+    Then the output should contain:
+    """
+    add :: Num, Num => Num
+    """
+
+  Scenario: functype on class method
+    Given a file named "class_method_functype.rb" with:
+    """ruby
+    require "./example"
+    puts Example.functype(:greeting)
+    """
+    When I run `ruby class_method_functype.rb`
+    Then the output should contain:
+    """
+    greeting :: String => String
+    """
+
+  Scenario: functype on singleton method
+    Given a file named "singleton_method_functype.rb" with:
+    """ruby
+    require "./example"
+    puts Example.functype(:increment)
+    """
+    When I run `ruby singleton_method_functype.rb`
+    Then the output should contain:
+    """
+    increment :: Num => Num
+    """

data/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
+    """