contracts 0.7 → 0.8

data/benchmarks/wrap_test.rb

@@ -1,4 +1,4 @@
-require 'benchmark'
+require "benchmark"
 
 module Wrapper
   def self.extended(klass)
@@ -26,9 +26,9 @@ module Wrapper
 end
 
 class NotWrapped
-def add a, b
-  a + b
-end
+  def add a, b
+    a + b
+  end
 end
 
 class Wrapped
@@ -38,22 +38,20 @@ class Wrapped
   end
 end
 
-
 w = Wrapped.new
 nw = NotWrapped.new
-#p w.add(1, 4)
-#exit
+# p w.add(1, 4)
+# exit
 # 30 is the width of the output column
 Benchmark.bm 30 do |x|
-  x.report 'wrapped' do
-    100000.times do |_|
+  x.report "wrapped" do
+    100_000.times do |_|
       w.add(rand(1000), rand(1000))
     end
   end
-  x.report 'not wrapped' do
-    100000.times do |_|
-      nw.add(rand(1000), rand(1000))      
+  x.report "not wrapped" do
+    100_000.times do |_|
+      nw.add(rand(1000), rand(1000))
     end
   end
 end
-

data/contracts.gemspec

@@ -1,4 +1,4 @@
-require File.expand_path(File.join(__FILE__, '../lib/contracts/version'))
+require File.expand_path(File.join(__FILE__, "../lib/contracts/version"))
 
 Gem::Specification.new do |s|
   s.name        = "contracts"

data/lib/contracts.rb

@@ -1,12 +1,12 @@
-require 'contracts/core_ext'
-require 'contracts/support'
-require 'contracts/method_reference'
-require 'contracts/errors'
-require 'contracts/decorators'
-require 'contracts/eigenclass'
-require 'contracts/builtin_contracts'
-require 'contracts/modules'
-require 'contracts/invariants'
+require "contracts/builtin_contracts"
+require "contracts/decorators"
+require "contracts/eigenclass"
+require "contracts/errors"
+require "contracts/formatters"
+require "contracts/invariants"
+require "contracts/method_reference"
+require "contracts/modules"
+require "contracts/support"
 
 module Contracts
   def self.included(base)
@@ -26,7 +26,7 @@ module Contracts
 
     base.instance_eval do
       def functype(funcname)
-        contracts = self.decorated_methods[:class_methods][funcname]
+        contracts = decorated_methods[:class_methods][funcname]
         if contracts.nil?
           "No contract for #{self}.#{funcname}"
         else
@@ -39,6 +39,13 @@ module Contracts
       unless base.instance_of?(Module)
         def Contract(*args)
           return if ENV["NO_CONTRACTS"]
+          if self.class == Module
+            puts %{
+Warning: You have added a Contract on a module function
+without including Contracts::Modules. Your Contract will
+just be ignored. Please include Contracts::Modules into
+your module.}
+          end
           self.class.Contract(*args)
         end
       end
@@ -65,28 +72,51 @@ class Contract < Contracts::Decorator
   # Default implementation of failure_callback. Provided as a block to be able
   # to monkey patch #failure_callback only temporary and then switch it back.
   # First important usage - for specs.
-  DEFAULT_FAILURE_CALLBACK = Proc.new do |data|
-    raise data[:contracts].failure_exception.new(failure_msg(data), data)
+  DEFAULT_FAILURE_CALLBACK = proc do |data|
+    fail data[:contracts].failure_exception.new(failure_msg(data), data)
   end
 
   attr_reader :args_contracts, :ret_contract, :klass, :method
-  # decorator_name :contract
   def initialize(klass, method, *contracts)
     if contracts[-1].is_a? Hash
       # internally we just convert that return value syntax back to an array
       @args_contracts = contracts[0, contracts.size - 1] + contracts[-1].keys
       @ret_contract = contracts[-1].values[0]
-      @args_validators = @args_contracts.map do |contract|
-        Contract.make_validator(contract)
-      end
-      @ret_validator = Contract.make_validator(@ret_contract)
     else
-      fail "It looks like your contract for #{method} doesn't have a return value. A contract should be written as `Contract arg1, arg2 => return_value`."
+      fail %{
+        It looks like your contract for #{method} doesn't have a return value.
+        A contract should be written as `Contract arg1, arg2 => return_value`.
+      }.strip
+    end
+
+    @args_validators = args_contracts.map do |contract|
+      Contract.make_validator(contract)
     end
-    @klass, @method= klass, method
-    @has_func_contracts = args_contracts.index do |contract|
-      contract.is_a? Contracts::Func
+
+    @args_contract_index = args_contracts.index do |contract|
+      contract.is_a? Contracts::Args
     end
+
+    @ret_validator = Contract.make_validator(ret_contract)
+
+    # == @has_proc_contract
+    last_contract = args_contracts.last
+    is_a_proc = last_contract.is_a?(Class) && (last_contract <= Proc || last_contract <= Method)
+
+    @has_proc_contract = is_a_proc || last_contract.is_a?(Contracts::Func)
+    # ====
+
+    # == @has_options_contract
+    last_contract = args_contracts.last
+    penultimate_contract = args_contracts[-2]
+    @has_options_contract = if @has_proc_contract
+                              penultimate_contract.is_a?(Hash)
+                            else
+                              last_contract.is_a?(Hash)
+                            end
+    # ===
+
+    @klass, @method = klass, method
   end
 
   def pretty_contract c
@@ -94,8 +124,8 @@ class Contract < Contracts::Decorator
   end
 
   def to_s
-    args = @args_contracts.map { |c| pretty_contract(c) }.join(", ")
-    ret = pretty_contract(@ret_contract)
+    args = args_contracts.map { |c| pretty_contract(c) }.join(", ")
+    ret = pretty_contract(ret_contract)
     ("#{args} => #{ret}").gsub("Contracts::", "")
   end
 
@@ -103,27 +133,22 @@ class Contract < Contracts::Decorator
   # This function is used by the default #failure_callback method
   # and uses the hash passed into the failure_callback method.
   def self.failure_msg(data)
-   expected = if data[:contract].to_s == "" || data[:contract].is_a?(Hash)
-                data[:contract].inspect
-              else
-                data[:contract].to_s
-              end
-
-   position = Contracts::Support.method_position(data[:method])
-   method_name = Contracts::Support.method_name(data[:method])
-
-   header = if data[:return_value]
-     "Contract violation for return value:"
-   else
-     "Contract violation for argument #{data[:arg_pos]} of #{data[:total_args]}:"
-   end
-
-%{#{header}
-    Expected: #{expected},
-    Actual: #{data[:arg].inspect}
-    Value guarded in: #{data[:class]}::#{method_name}
-    With Contract: #{data[:contracts]}
-    At: #{position} }
+    expected = Contracts::Formatters::Expected.new(data[:contract]).contract
+    position = Contracts::Support.method_position(data[:method])
+    method_name = Contracts::Support.method_name(data[:method])
+
+    header = if data[:return_value]
+               "Contract violation for return value:"
+             else
+               "Contract violation for argument #{data[:arg_pos]} of #{data[:total_args]}:"
+             end
+
+    %{#{header}
+        Expected: #{expected},
+        Actual: #{data[:arg].inspect}
+        Value guarded in: #{data[:class]}::#{method_name}
+        With Contract: #{data[:contracts]}
+        At: #{position} }
   end
 
   # Callback for when a contract fails. By default it raises
@@ -139,7 +164,7 @@ class Contract < Contracts::Decorator
   #     puts failure_msg(data)
   #     exit
   #   end
-  def self.failure_callback(data, use_pattern_matching=true)
+  def self.failure_callback(data, use_pattern_matching = true)
     if data[:contracts].pattern_match? && use_pattern_matching
       return DEFAULT_FAILURE_CALLBACK.call(data)
     end
@@ -194,29 +219,29 @@ class Contract < Contracts::Decorator
       contract
     elsif klass == Array
       # e.g. [Num, String]
-      # TODO account for these errors too
-      lambda { |arg|
+      # TODO: account for these errors too
+      lambda do |arg|
         return false unless arg.is_a?(Array) && arg.length == contract.length
         arg.zip(contract).all? do |_arg, _contract|
           Contract.valid?(_arg, _contract)
         end
-      }
+      end
     elsif klass == Hash
       # e.g. { :a => Num, :b => String }
-      lambda { |arg|
+      lambda do |arg|
         return false unless arg.is_a?(Hash)
         contract.keys.all? do |k|
           Contract.valid?(arg[k], contract[k])
         end
-      }
+      end
     elsif klass == Contracts::Args
-      lambda { |arg|
+      lambda do |arg|
         Contract.valid?(arg, contract.contract)
-      }
+      end
     elsif klass == Contracts::Func
-      lambda { |arg|
+      lambda do |arg|
         arg.is_a?(Method) || arg.is_a?(Proc)
-      }
+      end
     else
       # classes and everything else
       # e.g. Fixnum, Num
@@ -238,78 +263,111 @@ class Contract < Contracts::Decorator
     call_with(nil, *args, &blk)
   end
 
-  def call_with(this, *args, &blk)
-    _args = blk ? args + [blk] : args
-
-    size = @args_contracts.size
+  # if we specified a proc in the contract but didn't pass one in,
+  # it's possible we are going to pass in a block instead. So lets
+  # append a nil to the list of args just so it doesn't fail.
 
-    last_contract = @args_contracts.last
-    proc_present = (Contracts::Func === last_contract ||
-      (Class === last_contract && (last_contract <= Proc || last_contract <= Method)))
-
-    _splat_index = proc_present ? -2 : -1
-    splat_present = Contracts::Args === @args_contracts[_splat_index]
-    splat_index = size + _splat_index
-    splat_index += 1 unless splat_present
+  # a better way to handle this might be to take this into account
+  # before throwing a "mismatched # of args" error.
+  def maybe_append_block! args, blk
+    return unless @has_proc_contract && !blk &&
+        (@args_contract_index || args.size < args_contracts.size)
+    args << nil
+  end
 
-    # Explicitly append blk=nil if nil != Proc contract violation
-    # anticipated
-    if proc_present && !blk && (splat_present || _args.size < size)
-      _args << nil
+  # Same thing for when we have named params but didn't pass any in.
+  def maybe_append_options! args, blk
+    return 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
+  end
 
-    # Size of our iteration is either count of arguments or count of
-    # contracts. Without splat - count of arguments, with splat -
-    # min(count of contracts, count of arguments)
-    _size = _args.size
-    iteration_size = _size
-    iteration_size = size if !splat_present && size < _size
-
-    # check contracts on arguments
-    # fun fact! This is significantly faster than .zip (3.7 secs vs 4.7 secs). Why??
-
-    # times is faster than (0..args.size).each
-    iteration_size.times do |i|
-      # this is done to account for extra args (for *args)
-      j = i > splat_index ? splat_index : i
-      j = size - 1 if i == _size - 1 && proc_present
-      #unless true #@args_contracts[i].valid?(args[i])
-      unless @args_validators[j][_args[i]]
-        call_function = Contract.failure_callback({:arg => _args[i], :contract => @args_contracts[j], :class => @klass, :method => @method, :contracts => self, :arg_pos => i+1, :total_args => _size})
-        return unless call_function
+  def call_with(this, *args, &blk)
+    args << blk if blk
+
+    # Explicitly append blk=nil if nil != Proc contract violation anticipated
+    maybe_append_block!(args, blk)
+
+    # Explicitly append options={} if Hash contract is present
+    maybe_append_options!(args, blk)
+
+    # Loop forward validating the arguments up to the splat (if there is one)
+    (@args_contract_index || args.size).times do |i|
+      contract = args_contracts[i]
+      arg = args[i]
+      validator = @args_validators[i]
+
+      unless validator && validator[arg]
+        return unless Contract.failure_callback(:arg => arg,
+                                                :contract => contract,
+                                                :class => klass,
+                                                :method => method,
+                                                :contracts => self,
+                                                :arg_pos => i+1,
+                                                :total_args => args.size)
+      end
+
+      if contract.is_a?(Contracts::Func)
+        args[i] = Contract.new(klass, arg, *contract.contracts)
       end
     end
 
-    if @has_func_contracts
-      # contracts on methods
-      contracts_size = @args_contracts.size
-      @args_contracts.each_with_index do |contract, i|
-        next if contracts_size - 1 == i && proc_present && blk
+    # If there is a splat loop backwards to the lower index of the splat
+    # Once we hit the splat in this direction set its upper index
+    # Keep validating but use this upper index to get the splat validator.
+    if @args_contract_index
+      splat_upper_index = @args_contract_index
+      (args.size - @args_contract_index).times do |i|
+        arg = args[args.size - 1 - i]
 
-        if contract.is_a?(Contracts::Func)
-          args[i] = Contract.new(@klass, args[i], *contract.contracts)
+        if args_contracts[args_contracts.size - 1 - i].is_a?(Contracts::Args)
+          splat_upper_index = i
+        end
+
+        # Each arg after the spat is found must use the splat validator
+        j = i < splat_upper_index ? i : splat_upper_index
+        contract = args_contracts[args_contracts.size - 1 - j]
+        validator = @args_validators[args_contracts.size - 1 - j]
+
+        unless validator && validator[arg]
+          return unless Contract.failure_callback(:arg => arg,
+                                                  :contract => contract,
+                                                  :class => klass,
+                                                  :method => method,
+                                                  :contracts => self,
+                                                  :arg_pos => i-1,
+                                                  :total_args => args.size)
         end
-      end
 
-      if proc_present && blk && last_contract.is_a?(Contracts::Func)
-        blk_contract = Contract.new(@klass, blk, *last_contract.contracts)
-        blk = Proc.new { |*args, &blk| blk_contract.call(*args, &blk) }
+        if contract.is_a?(Contracts::Func)
+          args[args.size - 1 - i] = Contract.new(klass, arg, *contract.contracts)
+        end
       end
     end
 
-    result = if @method.respond_to?(:call)
-      # proc, block, lambda, etc
-      @method.call(*args, &blk)
-    else
-      # original method name referrence
-      @method.send_to(this, *args, &blk)
-    end
+    # If we put the block into args for validating, restore the args
+    args.slice!(-1) if blk
+    result = if method.respond_to?(:call)
+               # proc, block, lambda, etc
+               method.call(*args, &blk)
+             else
+               # original method name referrence
+               method.send_to(this, *args, &blk)
+             end
 
     unless @ret_validator[result]
-      Contract.failure_callback({:arg => result, :contract => @ret_contract, :class => @klass, :method => @method, :contracts => self, :return_value => true})
+      Contract.failure_callback(:arg => result,
+                                :contract => ret_contract,
+                                :class => klass,
+                                :method => method,
+                                :contracts => self,
+                                :return_value => true)
     end
 
-    this.verify_invariants!(@method) if this.respond_to?(:verify_invariants!)
+    this.verify_invariants!(method) if this.respond_to?(:verify_invariants!)
 
     result
   end

data/lib/contracts/builtin_contracts.rb

@@ -1,22 +1,23 @@
-require 'contracts/testable'
-
-=begin rdoc
-This module contains all the builtin contracts.
-If you want to use them, first:
-  
-  import Contracts
-
-And then use these or write your own!
-
-A simple example:
-
-  Contract Num, Num => Num
-  def add(a, b)
-     a + b
-   end
-
-The contract is <tt>Contract Num, Num, Num</tt>. That says that the +add+ function takes two numbers and returns a number.
-=end
+require "contracts/testable"
+require "contracts/formatters"
+
+# rdoc
+# This module contains all the builtin contracts.
+# If you want to use them, first:
+#
+#   import Contracts
+#
+# And then use these or write your own!
+#
+# A simple example:
+#
+#   Contract Num, Num => Num
+#   def add(a, b)
+#     a + b
+#   end
+#
+# The contract is <tt>Contract Num, Num, Num</tt>.
+# That says that the +add+ function takes two numbers and returns a number.
 module Contracts
   # Check that an argument is +Numeric+.
   class Num
@@ -29,7 +30,7 @@ module Contracts
     end
 
     def self.test_data
-      [-1, 0, 1, 1.5, 50000]
+      [-1, 0, 1, 1.5, 50_000]
     end
   end
 
@@ -63,6 +64,21 @@ module Contracts
     end
   end
 
+  # Check that an argument is a natural number.
+  class Nat
+    def self.valid? val
+      val >= 0 && val.integer?
+    end
+
+    def testable?
+      true
+    end
+
+    def self.test_data
+      (0..5).map { |n| n * rand(999) }
+    end
+  end
+
   # Passes for any argument.
   class Any
     def self.valid? val
@@ -86,8 +102,9 @@ module Contracts
   #
   # Of course, <tt>.new</tt> still works.
   class CallableClass
+    include ::Contracts::Formatters
     def self.[](*vals)
-      self.new(*vals)
+      new(*vals)
     end
   end
 
@@ -107,20 +124,22 @@ module Contracts
     end
 
     def to_s
-      @vals[0, @vals.size-1].join(", ") + " or " + @vals[-1].to_s
+      @vals[0, @vals.size-1].map do |x|
+        InspectWrapper.create(x)
+      end.join(", ") + " or " + InspectWrapper.create(@vals[-1]).to_s
     end
 
     # this can only be tested IF all the sub-contracts have a test_data method
     def testable?
       @vals.all? do |val|
         Testable.testable?(val)
-      end    
+      end
     end
 
     def test_data
-      @vals.map { |val|
+      @vals.map do |val|
         Testable.test_data(val)
-      }.flatten
+      end.flatten
     end
   end
 
@@ -141,25 +160,27 @@ module Contracts
     end
 
     def to_s
-      @vals[0, @vals.size-1].join(", ") + " xor " + @vals[-1].to_s
+      @vals[0, @vals.size-1].map do |x|
+        InspectWrapper.create(x)
+      end.join(", ") + " xor " + InspectWrapper.create(@vals[-1]).to_s
     end
 
     def testable?
       @vals.all? do |val|
         Testable.testable? val
-      end    
+      end
     end
 
     def test_data
-      @vals.map { |val|
+      @vals.map do |val|
         Testable.test_data val
-      }.flatten
-    end    
-  end  
+      end.flatten
+    end
+  end
 
   # Takes a variable number of contracts.
   # The contract passes if all contracts pass.
-  # Example: <tt>And[Fixnum, Float]</tt>  
+  # Example: <tt>And[Fixnum, Float]</tt>
   class And < CallableClass
     def initialize(*vals)
       @vals = vals
@@ -173,7 +194,9 @@ module Contracts
     end
 
     def to_s
-      @vals[0, @vals.size-1].join(", ") + " and " + @vals[-1].to_s
+      @vals[0, @vals.size-1].map do |x|
+        InspectWrapper.create(x)
+      end.join(", ") + " and " + InspectWrapper.create(@vals[-1]).to_s
     end
   end
 
@@ -215,10 +238,10 @@ module Contracts
 
     def to_s
       "a value that returns true for all of #{@meths.inspect}"
-    end  
+    end
   end
 
-  # Takes a class +A+. If argument is an object of type +A+, the contract passes.
+  # Takes a class +A+. If argument is object of type +A+, the contract passes.
   # If it is a subclass of A (or not related to A in any way), it fails.
   # Example: <tt>Exactly[Numeric]</tt>
   class Exactly < CallableClass
@@ -234,7 +257,24 @@ module Contracts
       "exactly #{@cls.inspect}"
     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>
+  class Eq < CallableClass
+    def initialize(value)
+      @value = value
+    end
+
+    def valid?(val)
+      @value.equal?(val)
+    end
+
+    def to_s
+      "to be equal to #{@value.inspect}"
+    end
+  end
+
   # Takes a variable number of contracts. The contract
   # passes if all of those contracts fail for the given argument.
   # Example: <tt>Not[nil]</tt>
@@ -281,8 +321,12 @@ module Contracts
     end
 
     def test_data
-      [[], [Testable.test_data(@contract)], [Testable.test_data(@contract), Testable.test_data(@contract)]]
-    end    
+      [
+        [],
+        [Testable.test_data(@contract)],
+        [Testable.test_data(@contract), Testable.test_data(@contract)]
+      ]
+    end
   end
 
   # Used for <tt>*args</tt> (variadic functions). Takes a contract
@@ -304,8 +348,12 @@ module Contracts
     end
 
     def test_data
-      [[], [Testable.test_data(@contract)], [Testable.test_data(@contract), Testable.test_data(@contract)]]
-    end    
+      [
+        [],
+        [Testable.test_data(@contract)],
+        [Testable.test_data(@contract), Testable.test_data(@contract)]
+      ]
+    end
   end
 
   class Bool
@@ -324,14 +372,14 @@ module Contracts
     end
 
     def valid?(hash)
-      keys_match = hash.keys.map {|k| Contract.valid?(k, @key) }.all?
-      vals_match = hash.values.map {|v| Contract.valid?(v, @value) }.all?
+      keys_match = hash.keys.map { |k| Contract.valid?(k, @key) }.all?
+      vals_match = hash.values.map { |v| Contract.valid?(v, @value) }.all?
 
       [keys_match, vals_match].all?
     end
 
     def to_s
-      "Hash<#{@key.to_s}, #{@value.to_s}>"
+      "Hash<#{@key}, #{@value}>"
     end
   end
 
@@ -344,51 +392,51 @@ module Contracts
     end
   end
 
-  class ::Hash
-    def testable?
-      self.values.all? do |val|
-        Testable.testable?(val)
-      end
-    end
-
-    def test_data
-      keys = self.keys
-      _vals = keys.map do |key|
-        ret = Testable.test_data(self[key])
-        if ret.is_a? Array
-          ret
-        else
-          [ret]
-        end
-      end
-      all_vals = Testable.product(_vals)
-      hashes = []
-      all_vals.each do |vals|
-        hash = {}
-        keys.zip(vals).each do |key, val|
-          hash[key] = val
-        end
-        hashes << hash
-      end
-      hashes
-    end
-  end
-
-  class ::String
-    def self.testable?
-      true
-    end
-
-    def self.test_data
-      # send a random string
-      ('a'..'z').to_a.shuffle[0, 10].join
-    end
-  end
+  # class ::Hash
+  #   def testable?
+  #     values.all? do |val|
+  #       Testable.testable?(val)
+  #     end
+  #   end
+
+  #   def test_data
+  #     keys = self.keys
+  #     _vals = keys.map do |key|
+  #       ret = Testable.test_data(self[key])
+  #       if ret.is_a? Array
+  #         ret
+  #       else
+  #         [ret]
+  #       end
+  #     end
+  #     all_vals = Testable.product(_vals)
+  #     hashes = []
+  #     all_vals.each do |vals|
+  #       hash = {}
+  #       keys.zip(vals).each do |key, val|
+  #         hash[key] = val
+  #       end
+  #       hashes << hash
+  #     end
+  #     hashes
+  #   end
+  # end
+
+  # class ::String
+  #   def self.testable?
+  #     true
+  #   end
+
+  #   def self.test_data
+  #     # send a random string
+  #     ("a".."z").to_a.shuffle[0, 10].join
+  #   end
+  # end
 
   # Used to define contracts on functions passed in as arguments.
   # Example: <tt>Func[Num => Num] # the function should take a number and return a number</tt>
   class Func < CallableClass
-    attr_reader :contracts    
+    attr_reader :contracts
     def initialize(*contracts)
       @contracts = contracts
     end