contracts 0.5 → 0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 77eb6f2fcb9b44586ae85de49add3fff7e1ece96
-  data.tar.gz: 43d47be3ae6f1b13b997dde2ba6701b5578f84a8
+  metadata.gz: 2aee00ef1803ee1ac8e84e96156494f7b7c4162a
+  data.tar.gz: a3798c342c9b29170f523f23083baeb2553cbd83
 SHA512:
-  metadata.gz: adaf871d3c827fcfad8b1ea3731d34ddc5023ab4d952a668c797e89bff7c798c1464db1acf80ae1eb446867ba817e56fc3be0c9401dd3e35d6aedea54db69c52
-  data.tar.gz: 297cc7359bf60acac92450b4f2c1a96bae8e845dedf3f088b01f86e7271f2d312d4449d2c908a5ebacadd46f1f9f2031a4ee5eccd8b35bf35d3420d5b95a821c
+  metadata.gz: d1404d6dd2fe5212b9c7a8bfa682b982bf612161200e33bc14ab73609eaac0681b85540a182a3d4d2437d3446380241785d229b6a8145c5a8c3fda8e37f682f5
+  data.tar.gz: 0912d5946702185218f94d1058577e92fd9f7b668e248ab4d796e67b620455f4a43e2a0e02d4871f8def9c8666feb3f4343c4f3f6d04d6c1a25b97541c7afd27

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    contracts (0.4)
+    contracts (0.5)
 
 GEM
   remote: http://rubygems.org/

data/README.md

@@ -73,3 +73,4 @@ Copyright 2012 [Aditya Bhargava](http://adit.io).
 Major improvements by [Alexey Fedorov](https://github.com/waterlink).
 
 BSD Licensed.
+

data/TUTORIAL.md

@@ -405,7 +405,9 @@ If you want to disable contracts, set the `NO_CONTRACTS` environment variable. T
 
 ## Method overloading
 
-You can use contracts for method overloading! For example, here's a factorial function without method overloading:
+You can use contracts for method overloading! This is commonly called "pattern matching" in functional programming languages.
+
+For example, here's a factorial function without method overloading:
 
 ```ruby
 Contract Num => Num
@@ -434,6 +436,45 @@ end
 
 For an argument, each function will be tried in order. The first function that doesn't raise a `ContractError` will be used. So in this case, if x == 1, the first function will be used. For all other values, the second function will be used.
 
+This allows you write methods more declaratively, rather than using conditional branching. This feature is not only useful for recursion; you can use it to keep parallel use cases separate:
+
+```ruby
+Contract And[Num, lambda{|n| n < 12 }] => Ticket
+def get_ticket(age)
+  ChildTicket.new(age: age)
+end
+
+Contract And[Num, lambda{|n| n >= 12 }] => Ticket
+def get_ticket(age)
+  AdultTicket.new(age: age)
+end
+
+```
+
+Note that the second `get_ticket` contract above could have been simplified to:
+
+```ruby
+Contract 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.
+
+## Contracts in modules
+
+To use contracts on module you need to include both `Contracts` and `Contracts::Modules` into it:
+
+```ruby
+module M
+  include Contracts
+  include Contracts::Modules
+
+  Contract String => String
+  def self.parse
+    # do some hard parsing
+  end
+end
+```
+
 ## Invariants
 
 Invariants are conditions on objects that should always hold. If after any method call on given object, any of the Invariants fails, then Invariant violation error will be generated.

data/benchmarks/bench.rb

@@ -34,7 +34,7 @@ def benchmark
       1000000.times do |_|
         contracts_add(rand(1000), rand(1000))
       end
-    end  
+    end
   end
 end
 
@@ -48,12 +48,12 @@ def profile
   profilers << MethodProfiler.observe(UnboundMethod)
   10000.times do |_|
     contracts_add(rand(1000), rand(1000))
-  end  
+  end
   profilers.each { |p| puts p.report }
 end
 
 def ruby_prof
-RubyProf.start  
+RubyProf.start
     100000.times do |_|
       contracts_add(rand(1000), rand(1000))
     end

data/contracts.gemspec

@@ -3,7 +3,6 @@ require File.expand_path(File.join(__FILE__, '../lib/contracts/version'))
 Gem::Specification.new do |s|
   s.name        = "contracts"
   s.version     = Contracts::VERSION
-  s.date        = "2014-05-08"
   s.summary     = "Contracts for Ruby."
   s.description = "This library provides contracts for Ruby. Contracts let you clearly express how your code behaves, and free you from writing tons of boilerplate, defensive code."
   s.author      = "Aditya Bhargava"

data/lib/contracts.rb

@@ -1,54 +1,29 @@
+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'
 
-# @private
-# Base class for Contract errors
-#
-# If default failure callback is used it stores failure data
-class ContractBaseError < ArgumentError
-  attr_reader :data
-
-  def initialize(message, data)
-    super(message)
-    @data = data
-  end
-
-  # Used to convert to simple ContractError from other contract errors
-  def to_contract_error
-    self
-  end
-end
-
-# Default contract error
-#
-# If default failure callback is used, users normally see only these contract errors
-class ContractError < ContractBaseError
-end
-
-# @private
-# Special contract error used internally to detect pattern failure during pattern matching
-class PatternMatchingError < ContractBaseError
-  # Used to convert to ContractError from PatternMatchingError
-  def to_contract_error
-    ContractError.new(to_s, data)
-  end
-end
-
 module Contracts
   def self.included(base)
-    common base
+    common(base)
   end
 
   def self.extended(base)
-    common base
+    common(base)
   end
 
-  def self.common base
+  def self.common(base)
+    Eigenclass.lift(base)
+
     return if base.respond_to?(:Contract)
 
-    base.extend MethodDecorators
+    base.extend(MethodDecorators)
+
     base.instance_eval do
       def functype(funcname)
         contracts = self.decorated_methods[:class_methods][funcname]
@@ -59,10 +34,13 @@ module Contracts
         end
       end
     end
+
     base.class_eval do
-      def Contract(*args)
-        return if ENV["NO_CONTRACTS"]
-        self.class.Contract(*args)
+      unless base.instance_of?(Module)
+        def Contract(*args)
+          return if ENV["NO_CONTRACTS"]
+          self.class.Contract(*args)
+        end
       end
 
       def functype(funcname)
@@ -131,8 +109,8 @@ class Contract < Contracts::Decorator
                 data[:contract].to_s
               end
 
-   position = Support.method_position(data[:method])
-   method_name = Support.method_name(data[:method])
+   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:"
@@ -261,39 +239,72 @@ class Contract < Contracts::Decorator
   end
 
   def call_with(this, *args, &blk)
-
     _args = blk ? args + [blk] : args
 
+    size = @args_contracts.size
+
+    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
+
+    # Explicitly append blk=nil if nil != Proc contract violation
+    # anticipated
+    if proc_present && !blk && (splat_present || _args.size < size)
+      _args << nil
+    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??
-    last_index = @args_validators.size - 1
+
     # times is faster than (0..args.size).each
-    _args.size.times do |i|
+    iteration_size.times do |i|
       # this is done to account for extra args (for *args)
-      j = i < last_index ? i : last_index
+      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 => _args.size})
+        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
       end
     end
 
     if @has_func_contracts
       # contracts on methods
+      contracts_size = @args_contracts.size
       @args_contracts.each_with_index do |contract, i|
-        if contract.is_a? Contracts::Func
-        args[i] = Contract.new(@klass, args[i], *contract.contracts)
+        next if contracts_size - 1 == i && proc_present && blk
+
+        if contract.is_a?(Contracts::Func)
+          args[i] = Contract.new(@klass, args[i], *contract.contracts)
         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) }
+      end
     end
 
-    result = if @method.respond_to? :bind
-      # instance method
-      @method.bind(this).call(*args, &blk)
-    else
-      # class method
+    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})
     end

data/lib/contracts/core_ext.rb

@@ -0,0 +1,15 @@
+class Module
+  unless Object.respond_to?(:singleton_class)
+    # Compatibility with ruby 1.8
+    def singleton_class
+      class << self; self; end
+    end
+  end
+
+  unless Object.respond_to?(:singleton_class?)
+    # Compatibility with ruby 1.8
+    def singleton_class?
+      self <= Object.singleton_class
+    end
+  end
+end

data/lib/contracts/decorators.rb

@@ -8,6 +8,22 @@ module Contracts
       end
     end
 
+    module EigenclassWithOwner
+      def self.lift(eigenclass)
+        unless with_owner?(eigenclass)
+          raise Contracts::ContractsNotIncluded
+        end
+
+        eigenclass
+      end
+
+      private
+
+      def self.with_owner?(eigenclass)
+        eigenclass.respond_to?(:owner_class) && eigenclass.owner_class
+      end
+    end
+
     # first, when you write a contract, the decorate method gets called which
     # sets the @decorators variable. Then when the next method after the contract
     # is defined, method_added is called and we look at the @decorators variable
@@ -18,25 +34,32 @@ module Contracts
       super
     end
 
-    def singleton_method_added name
+    def singleton_method_added(name)
       common_method_added name, true
       super
     end
 
-    def common_method_added name, is_class_method
-      return unless @decorators
+    def pop_decorators
+      Array(@decorators).tap { @decorators = nil }
+    end
+
+    def fetch_decorators
+      pop_decorators + Eigenclass.lift(self).pop_decorators
+    end
+
+    def common_method_added(name, is_class_method)
+      decorators = fetch_decorators
+      return if decorators.empty?
 
-      decorators = @decorators.dup
-      @decorators = nil
       @decorated_methods ||= {:class_methods => {}, :instance_methods => {}}
 
       if is_class_method
-        method_reference = method(name)
+        method_reference = SingletonMethodReference.new(name, method(name))
         method_type = :class_methods
         # private_methods is an array of strings on 1.8 and an array of symbols on 1.9
         is_private = self.private_methods.include?(name) || self.private_methods.include?(name.to_s)
       else
-        method_reference = instance_method(name)
+        method_reference = MethodReference.new(name, instance_method(name))
         method_type = :instance_methods
         # private_instance_methods is an array of strings on 1.8 and an array of symbols on 1.9
         is_private = self.private_instance_methods.include?(name) || self.private_instance_methods.include?(name.to_s)
@@ -44,6 +67,7 @@ module Contracts
 
       @decorated_methods[method_type][name] ||= []
 
+      pattern_matching = false
       decorators.each do |klass, args|
         # a reference to the method gets passed into the contract here. This is good because
         # we are going to redefine this method with a new name below...so this reference is
@@ -51,14 +75,21 @@ module Contracts
         # We assume here that the decorator (klass) responds to .new
         decorator = klass.new(self, method_reference, *args)
         @decorated_methods[method_type][name] << decorator
+        pattern_matching ||= decorator.pattern_match?
       end
 
       if @decorated_methods[method_type][name].any? { |x| x.method != method_reference }
         @decorated_methods[method_type][name].each do |decorator|
           decorator.pattern_match!
         end
+
+        pattern_matching = true
       end
 
+      method_reference.make_alias(self)
+
+      return if ENV["NO_CONTRACTS"] && !pattern_matching
+
       # in place of this method, we are going to define our own method. This method
       # just calls the decorator passing in all args that were to be passed into the method.
       # The decorator in turn has a reference to the actual method, so it can call it
@@ -100,52 +131,54 @@ Here's why: Suppose you have this code:
     means you would always call Bar's to_s...infinite recursion! Instead, you want to
     call Foo's version of decorated_methods. So the line needs to be `current = #{self}`.
 =end
-      method_def = %{
-        def #{is_class_method ? "self." : ""}#{name}(*args, &blk)
-          current = #{self}
-          ancestors = current.ancestors
-          ancestors.shift # first one is just the class itself
-          while current && !current.respond_to?(:decorated_methods) || current.decorated_methods.nil?
-            current = ancestors.shift
-          end
-          if !current.respond_to?(:decorated_methods) || current.decorated_methods.nil?
-            raise "Couldn't find decorator for method " + self.class.name + ":#{name}.\nDoes this method look correct to you? If you are using contracts from rspec, rspec wraps classes in it's own class.\nLook at the specs for contracts.ruby as an example of how to write contracts in this case."
-          end
-          methods = current.decorated_methods[#{is_class_method ? ":class_methods" : ":instance_methods"}][#{name.inspect}]
-
-          # this adds support for overloading methods. Here we go through each method and call it with the arguments.
-          # If we get a ContractError, we move to the next function. Otherwise we return the result.
-          # If we run out of functions, we raise the last ContractError.
-          success = false
-          i = 0
-          result = nil
-          expected_error = methods[0].failure_exception
-          while !success
-            method = methods[i]
-            i += 1
-            begin
-              success = true
-              result = method.call_with(self, *args, &blk)
-            rescue expected_error => error
-              success = false
-              unless methods[i]
-                begin
-                  ::Contract.failure_callback(error.data, false)
-                rescue expected_error => final_error
-                  raise final_error.to_contract_error
-                end
+
+      current = self
+      method_reference.make_definition(self) do |*args, &blk|
+        ancestors = current.ancestors
+        ancestors.shift # first one is just the class itself
+        while current && !current.respond_to?(:decorated_methods) || current.decorated_methods.nil?
+          current = ancestors.shift
+        end
+        if !current.respond_to?(:decorated_methods) || current.decorated_methods.nil?
+          raise "Couldn't find decorator for method " + self.class.name + ":#{name}.\nDoes this method look correct to you? If you are using contracts from rspec, rspec wraps classes in it's own class.\nLook at the specs for contracts.ruby as an example of how to write contracts in this case."
+        end
+        methods = current.decorated_methods[method_type][name]
+
+        # this adds support for overloading methods. Here we go through each method and call it with the arguments.
+        # If we get a ContractError, we move to the next function. Otherwise we return the result.
+        # If we run out of functions, we raise the last ContractError.
+        success = false
+        i = 0
+        result = nil
+        expected_error = methods[0].failure_exception
+        while !success
+          method = methods[i]
+          i += 1
+          begin
+            success = true
+            result = method.call_with(self, *args, &blk)
+          rescue expected_error => error
+            success = false
+            unless methods[i]
+              begin
+                ::Contract.failure_callback(error.data, false)
+              rescue expected_error => final_error
+                raise final_error.to_contract_error
               end
             end
           end
-          result
         end
-        #{is_private ? "private #{name.inspect}" : ""}
-          }
+        result
+      end
 
-      class_eval method_def, __FILE__, __LINE__ + 1
+      method_reference.make_private(self) if is_private
     end
 
     def decorate(klass, *args)
+      if self.singleton_class?
+        return EigenclassWithOwner.lift(self).owner_class.decorate(klass, *args)
+      end
+
       @decorators ||= []
       @decorators << [klass, args]
     end
@@ -166,7 +199,6 @@ Here's why: Suppose you have this code:
       # inside, `decorate` is called with those params.
       MethodDecorators.module_eval <<-ruby_eval, __FILE__, __LINE__ + 1
         def #{klass}(*args, &blk)
-          return if ENV["NO_CONTRACTS"]
           decorate(#{klass}, *args, &blk)
         end
       ruby_eval