contracts 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7928ae4cc32437fe0b85893e7f381a47864309e8
-  data.tar.gz: cfdd1ee61dd1e002bec1337815f75ce56c942b0e
+  metadata.gz: 588796ed6d26a1394810a86debd6f0b285dfb7e1
+  data.tar.gz: bff5d90964ae5bb9911b66236c5898ad741c159b
 SHA512:
-  metadata.gz: a68ba2b3654e8882954789e2370a88108c822dc97d390062c9507ab06b56f4fb8fb6739b4051a6a71ad3648742969bf936f096892f78ab5bc831108d667c563d
-  data.tar.gz: 2da1f049afd136edfdea28b9b9e1b4142ec721151b44bfde574075786338cea065cffc00273815edcd7b7b84f49926826fc69ffda462d3b94a87a8ce1b4ad831
+  metadata.gz: 678e7911e3dee12d273a8839712583bd0cc1272bde6da8aa8bdc27685751a66c9c9a25c39b1182c6056ff1d8bce191b8982783a18abadeff2526501040f61133
+  data.tar.gz: 5c8b7cd54ebff1b8d9d75393a2c1f0d45df096c295c3387eefd54a1a01695afe8fe1ef4975bc09705d1a6d081761fe42ffb8512d926df6cc0104e10f764844c6

data/CHANGELOG.markdown

@@ -1,3 +1,11 @@
+## 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)
+- Bugfix: make KeywordArgs fail if unexpected keys are passed in - [Abe Voelker](https://github.com/abevoelker) [#187](https://github.com/egonSchiele/contracts.ruby/pull/187)
+- Feature: range contract added - [Oleksii Fedorov](https://github.com/waterlink) [#184](https://github.com/egonSchiele/contracts.ruby/pull/184)
+- Feature: enum contract added - [Dennis Günnewig](https://github.com/dg-ratiodata) [#181](https://github.com/egonSchiele/contracts.ruby/pull/181)
+
 ## v0.10.1
 
 - Enhancement: make `@pattern_match` instance variable not render ruby warning. Required to use new aruba versions in rspec tests - [Dennis Günnewig](https://github.com/dg-ratiodata) [#179](https://github.com/egonSchiele/contracts.ruby/pull/179)
@@ -18,7 +26,7 @@
 - MAJOR fix in pattern-matching: If the return contract for a pattern-matched function fails, it should NOT try the next pattern-match function. Pattern-matching is only for params, not return values.
 - raise an error if multiple defns have the same contract for pattern matching.
 
-- New syntax for functions with no input params (the old style still works)  
+- New syntax for functions with no input params (the old style still works)
   Old way:
   ```ruby
   Contract nil => 1

data/TUTORIAL.md

@@ -17,7 +17,7 @@ contracts.ruby brings code contracts to the Ruby language. Code contracts allow
 A simple example:
 
 ```ruby
-Contract Num, Num => Num
+Contract Contracts::Num, Contracts::Num => Contracts::Num
 def add(a, b)
   a + b
 end
@@ -31,9 +31,9 @@ Copy this code into a file and run it:
 require 'contracts'
 
 class Math
-  include Contracts
+  include Contracts::Core
 
-  Contract Num, Num => Num
+  Contract Contracts::Num, Contracts::Num => Contracts::Num
   def self.add(a, b)
     a + b
   end
@@ -88,6 +88,7 @@ contracts.ruby comes with a lot of built-in contracts, including the following:
   * [`SetOf`](http://www.rubydoc.info/gems/contracts/Contracts/SetOf) – checks that the argument is a set, and all elements pass the given contract, e.g. `SetOf[Num]`
   * [`HashOf`](http://www.rubydoc.info/gems/contracts/Contracts/HashOf) – checks that the argument is a hash, and all keys and values pass the given contract, e.g. `HashOf[Symbol => String]` or `HashOf[Symbol,String]`
   * [`RangeOf`](http://www.rubydoc.info/gems/contracts/Contracts/RangeOf) – checks that the argument is a range whose elements (#first and #last) pass the given contract, e.g. `RangeOf[Date]`
+  * [`Enum`](http://www.rubydoc.info/gems/contracts/Contracts/Enum) – checks that the argument is part of a given collection of objects, e.g. `Enum[:a, :b, :c]`
 
 * Keyword arguments
   * [`KeywordArgs`](http://www.rubydoc.info/gems/contracts/Contracts/KeywordArgs) – checks that the argument is an options hash, and all required keyword arguments are present, and all values pass their respective contracts, e.g. `KeywordArgs[:number => Num, :description => Optional[String]]`
@@ -104,6 +105,21 @@ contracts.ruby comes with a lot of built-in contracts, including the following:
 
 To see all the built-in contracts and their full descriptions, check out the [RDoc](http://rubydoc.info/gems/contracts/Contracts).
 
+It is recommended to use shortcut for referring builtin contracts:
+
+```ruby
+# define shortcut somewhere at the top level of your codebase:
+C = Contracts
+
+# and use it:
+Contract C::Maybe[C::Num], String => C::Num
+```
+
+Shortcut name should not be necessary `C`, can be anything that you are comfort
+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::`.
+
 ## More Examples
 
 ### Hello, World
@@ -126,7 +142,7 @@ You always need to specify a contract for the return value. In this example, `he
 ### A Double Function
 
 ```ruby
-Contract Or[Fixnum, Float] => Or[Fixnum, Float]
+Contract C::Or[Fixnum, Float] => C::Or[Fixnum, Float]
 def double(x)
   2 * x
 end
@@ -136,19 +152,19 @@ Sometimes you want to be able to choose between a few contracts. `Or` takes a va
 This introduces some new syntax. One of the valid values for a contract is an instance of a class that responds to the `valid?` method. This is what `Or[Fixnum, Float]` is. The longer way to write it would have been:
 
 ```ruby
-Contract Or.new(Fixnum, Float) => Or.new(Fixnum, Float)
+Contract C::Or.new(Fixnum, Float) => C::Or.new(Fixnum, Float)
 ```
 
 All the built-in contracts have overridden the square brackets (`[]`) to give the same functionality. So you could write
 
 ```ruby
-Contract Or[Fixnum, Float] => Or[Fixnum, Float]
+Contract C::Or[Fixnum, Float] => C::Or[Fixnum, Float]
 ```
 
 or
 
 ```ruby
-Contract Or.new(Fixnum, Float) => Or.new(Fixnum, Float)
+Contract C::Or.new(Fixnum, Float) => C::Or.new(Fixnum, Float)
 ```
 
 whichever you prefer. They both mean the same thing here: make a new instance of `Or` with `Fixnum` and `Float`. Use that instance to validate the argument.
@@ -156,7 +172,7 @@ whichever you prefer. They both mean the same thing here: make a new instance of
 ### A Product Function
 
 ```ruby
-Contract ArrayOf[Num] => Num
+Contract C::ArrayOf[C::Num] => C::Num
 def product(vals)
   total = 1
   vals.each do |val|
@@ -179,7 +195,7 @@ product([1, 2, 3, "foo"])
 ### Another Product Function
 
 ```ruby
-Contract Args[Num] => Num
+Contract C::Args[C::Num] => C::Num
 def product(*vals)
   total = 1
   vals.each do |val|
@@ -203,7 +219,7 @@ If an array is one of the arguments and you know how many elements it's going to
 
 ```ruby
 # a function that takes an array of two elements...a person's age and a person's name.
-Contract [Num, String] => nil
+Contract [C::Num, String] => nil
 def person(data)
   p data
 end
@@ -217,7 +233,7 @@ Here's a contract that requires a Hash. We can put contracts on each of the keys
 
 ```ruby
 # note the parentheses around the hash; without those you would get a syntax error
-Contract ({ :age => Num, :name => String }) => nil
+Contract ({ :age => C::Num, :name => String }) => nil
 def person(data)
   p data
 end
@@ -241,7 +257,7 @@ even though we don't specify a type for `:foo`.
 Peruse this contract on the keys and values of a Hash.
 
 ```ruby
-Contract HashOf[Symbol, Num] => Num
+Contract C::HashOf[Symbol, C::Num] => C::Num
 def give_largest_value(hsh)
   hsh.values.max
 end
@@ -269,14 +285,14 @@ def connect(host, port:, user:, password:)
 You can of course put `Hash` contract on it:
 
 ```ruby
-Contract String, { :port => Num, :user => String, :password => String } => Connection
+Contract String, { :port => C::Num, :user => String, :password => String } => Connection
 def connect(host, port:, user:, password:)
 ```
 
 But this will not quite work if you want to have a default values:
 
 ```ruby
-Contract String, { :port => Num, :user => String, :password => String } => Connection
+Contract String, { :port => C::Num, :user => String, :password => String } => Connection
 def connect(host, port: 5000, user:, password:)
   # ...
 end
@@ -296,13 +312,13 @@ ContractError: Contract violation for argument 2 of 2:
         At: (irb):12
 ```
 
-This can be fixed with contract `{ :port => Maybe[Num], ... }`, but that will
+This can be fixed with contract `{ :port => C::Maybe[C::Num], ... }`, but that will
 allow `nil` to be passed in, which is not the original intent.
 
 So that is where `KeywordArgs` and `Optional` contracts jump in:
 
 ```ruby
-Contract String, KeywordArgs[ :port => Optional[Num], :user => String, :password => String ] => Connection
+Contract String, C::KeywordArgs[ :port => C::Optional[C::Num], :user => String, :password => String ] => Connection
 def connect(host, port: 5000, user:, password:)
 ```
 
@@ -319,7 +335,7 @@ def map(arr, func)
 `map` takes an array, and a function. Suppose you want to add a contract to this function. You could try this:
 
 ```ruby
-Contract ArrayOf[Any], Proc => ArrayOf[Any]
+Contract C::ArrayOf[C::Any], Proc => C::ArrayOf[C::Any]
 def map(arr, func)
 ```
 
@@ -334,7 +350,7 @@ But suppose you want to have a contract on the Proc too! Suppose you want to mak
 Here's a `map` function that requires an array of numbers, and a function that takes a number and returns a number:
 
 ```ruby
-Contract ArrayOf[Num], Func[Num => Num] => ArrayOf[Num]
+Contract C::ArrayOf[C::Num], C::Func[C::Num => C::Num] => C::ArrayOf[C::Num]
 def map(arr, func)
   ret = []
   arr.each do |x|
@@ -362,7 +378,7 @@ def map(arr, &block)
 NOTE: This is not valid:
 
 ```ruby
-Contract ArrayOf[Num], Func => ArrayOf[Num]
+Contract C::ArrayOf[C::Num], C::Func => C::ArrayOf[C::Num]
 def map(arr, &func)
 ```
 
@@ -372,7 +388,7 @@ Here I am using `Func` without specifying a contract, like `Func[Num => Num]`. T
 Treat the return value as an array. For example, here's a function that returns two numbers:
 
 ```ruby
-Contract Num => [Num, Num]
+Contract C::Num => [C::Num, C::Num]
 def mult(x)
   return x, x+1
 end
@@ -383,7 +399,7 @@ end
 If you use a contract a lot, it's a good idea to give it a meaningful synonym that tells the reader more about what your code returns. For example, suppose you have many functions that return a `Hash` or `nil`. If a `Hash` is returned, it contains information about a person. Your contact might look like this:
 
 ```ruby
-Contract String => Or[Hash, nil]
+Contract String => C::Or[Hash, nil]
 def some_func(str)
 ```
 
@@ -415,7 +431,7 @@ The first two don't need any extra work to define: you can just use any constant
 ### A Proc
 
 ```ruby
-Contract lambda { |x| x.is_a? Numeric } => Num
+Contract lambda { |x| x.is_a? Numeric } => C::Num
 def double(x)
 ```
 
@@ -460,7 +476,7 @@ The `Or` contract takes a sequence of contracts, and passes if any of them pass.
 This class inherits from `CallableClass`, which allows us to use `[]` when using the class:
 
 ```ruby
-Contract Or[Fixnum, Float] => Num
+Contract C::Or[Fixnum, Float] => C::Num
 def double(x)
   2 * x
 end
@@ -469,7 +485,7 @@ end
 Without `CallableClass`, we would have to use `.new` instead:
 
 ```ruby
-Contract Or.new(Fixnum, Float) => Num
+Contract C::Or.new(Fixnum, Float) => C::Num
 def double(x)
 # etc
 ```
@@ -543,10 +559,11 @@ Possible validator overrides:
 
 - `override_validator(MyCustomContract)` - allows to add some special behaviour for custom contracts,
 - `override_validator(Proc)` - e.g. `lambda { true }`,
-- `override_validator(Array)` - e.g. `[Num, String]`,
-- `override_validator(Hash)` - e.g. `{ :a => Num, :b => String }`,
-- `override_validator(Contracts::Args)` - e.g. `Args[Num]`,
-- `override_validator(Contracts::Func)` - e.g. `Func[Num => Num]`,
+- `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(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,
 - `override_validator(:class)` - allows to override how class/module contract constants are handled,
 - `override_validator(:default)` - otherwise, raw value contracts.
@@ -564,7 +581,7 @@ You can use contracts for method overloading! This is commonly called "pattern m
 For example, here's a factorial function without method overloading:
 
 ```ruby
-Contract Num => Num
+Contract C::Num => C::Num
 def fact x
   if x == 1
     x
@@ -582,7 +599,7 @@ def fact x
   x
 end
 
-Contract Num => Num
+Contract C::Num => C::Num
 def fact x
   x * fact(x - 1)
 end
@@ -608,7 +625,7 @@ end
 Note that the second `get_ticket` contract above could have been simplified to:
 
 ```ruby
-Contract Num => Ticket
+Contract C::Num => Ticket
 ```
 
 This is because the first contract eliminated the possibility of `age` being less than 12. However, the simpler contract is less explicit; you may want to "spell out" the age condition for clarity, especially if the method is overloaded with many contracts.
@@ -619,7 +636,7 @@ Usage is the same as contracts in classes:
 
 ```ruby
 module M
-  include Contracts
+  include Contracts::Core
 
   Contract String => String
   def self.parse
@@ -638,13 +655,13 @@ A simple example:
 
 ```ruby
 class MyBirthday < Struct.new(:day, :month)
-  include Contracts
+  include Contracts::Core
   include Contracts::Invariants
 
   invariant(:day) { 1 <= day && day <= 31 }
   invariant(:month) { 1 <= month && month <= 12 }
 
-  Contract None => Fixnum
+  Contract C::None => Fixnum
   def silly_next_day!
     self.day += 1
   end

data/lib/contracts.rb

@@ -9,48 +9,15 @@ require "contracts/engine"
 require "contracts/method_handler"
 require "contracts/validators"
 require "contracts/call_with"
+require "contracts/core"
 
 module Contracts
   def self.included(base)
-    common(base)
+    base.send(:include, Core)
   end
 
   def self.extended(base)
-    common(base)
-  end
-
-  def self.common(base)
-    return if base.respond_to?(:Contract)
-
-    base.extend(MethodDecorators)
-
-    base.instance_eval do
-      def functype(funcname)
-        contracts = Engine.fetch_from(self).decorated_methods_for(:class_methods, funcname)
-        if contracts.nil?
-          "No contract for #{self}.#{funcname}"
-        else
-          "#{funcname} :: #{contracts[0]}"
-        end
-      end
-    end
-
-    base.class_eval do
-      # TODO: deprecate
-      # Required when contracts are included in global scope
-      def Contract(*args)
-        self.class.Contract(*args)
-      end
-
-      def functype(funcname)
-        contracts = Engine.fetch_from(self.class).decorated_methods_for(:instance_methods, funcname)
-        if contracts.nil?
-          "No contract for #{self.class}.#{funcname}"
-        else
-          "#{funcname} :: #{contracts[0]}"
-        end
-      end
-    end
+    base.send(:extend, Core)
   end
 end
 
@@ -118,6 +85,7 @@ class Contract < Contracts::Decorator
     maybe_a_proc = last_contract.is_a?(Contracts::Maybe) && last_contract.include_proc?
 
     @has_proc_contract = is_a_proc || maybe_a_proc || last_contract.is_a?(Contracts::Func)
+
     # ====
 
     # == @has_options_contract
@@ -235,20 +203,24 @@ class Contract < Contracts::Decorator
 
   # a better way to handle this might be to take this into account
   # before throwing a "mismatched # of args" error.
+  # returns true if it appended nil
   def maybe_append_block! args, blk
-    return unless @has_proc_contract && !blk &&
+    return false unless @has_proc_contract && !blk &&
         (@args_contract_index || args.size < args_contracts.size)
     args << nil
+    true
   end
 
   # Same thing for when we have named params but didn't pass any in.
+  # returns true if it appended nil
   def maybe_append_options! args, blk
-    return unless @has_options_contract
+    return false unless @has_options_contract
     if @has_proc_contract && args_contracts[-2].is_a?(Hash) && !args[-2].is_a?(Hash)
       args.insert(-2, {})
     elsif args_contracts[-1].is_a?(Hash) && !args[-1].is_a?(Hash)
       args << {}
     end
+    true
   end
 
   # Used to determine type of failure exception this contract should raise in case of failure

data/lib/contracts/builtin_contracts.rb

@@ -201,6 +201,20 @@ module Contracts
     end
   end
 
+  # Takes a list of values, e.g. +[:a, :b, :c]+. If argument is included in
+  # the list, the contract passes.
+  #
+  # Example: <tt>Enum[:a, :b, :c]</tt>?
+  class Enum < CallableClass
+    def initialize(*vals)
+      @vals = vals
+    end
+
+    def valid?(val)
+      @vals.include? val
+    end
+  end
+
   # Takes a value +v+. If the argument is +.equal+ to +v+, the contract passes,
   # otherwise the contract fails.
   # Example: <tt>Eq[Class]</tt>
@@ -346,6 +360,7 @@ module Contracts
     end
 
     def valid?(hash)
+      return false unless hash.is_a?(Hash)
       keys_match = hash.keys.map { |k| Contract.valid?(k, @key) }.all?
       vals_match = hash.values.map { |v| Contract.valid?(v, @value) }.all?
 
@@ -371,6 +386,7 @@ module Contracts
     end
 
     def valid?(hash)
+      return false unless hash.keys - options.keys == []
       options.all? do |key, contract|
         Optional._valid?(hash, key, contract)
       end

data/lib/contracts/call_with.rb

@@ -4,7 +4,7 @@ module Contracts
       args << blk if blk
 
       # Explicitly append blk=nil if nil != Proc contract violation anticipated
-      maybe_append_block!(args, blk)
+      nil_block_appended = maybe_append_block!(args, blk)
 
       # Explicitly append options={} if Hash contract is present
       maybe_append_options!(args, blk)
@@ -66,7 +66,8 @@ module Contracts
       end
 
       # If we put the block into args for validating, restore the args
-      args.slice!(-1) if blk
+      # OR if we added a fake nil at the end because a block wasn't passed in.
+      args.slice!(-1) if blk || nil_block_appended
       result = if method.respond_to?(:call)
                  # proc, block, lambda, etc
                  method.call(*args, &blk)