contracts-lite 0.14.0 → 0.15.0

data/lib/contracts/contract.rb

@@ -0,0 +1,136 @@
+# This is the main Contract class. When you write a new contract, you'll
+# write it as:
+#
+#   Contract [contract names] => return_value
+#
+# This class also provides useful callbacks and a validation method.
+class Contract < Contracts::Decorator
+  extend Contracts::Validators
+  extend Contracts::FailureCallback
+  include Contracts::CallWith
+
+  # Used to verify if an argument satisfies a contract.
+  #
+  # Takes: an argument and a contract.
+  #
+  # Returns: a tuple: [Boolean, metadata]. The boolean indicates
+  # whether the contract was valid or not. If it wasn't, metadata
+  # contains some useful information about the failure.
+  def self.valid?(arg, contract)
+    make_validator(contract)[arg]
+  end
+
+  attr_reader :args_contracts, :ret_contract, :klass, :method, :ret_validator, :args_validators
+  def initialize(klass, method, *contracts)
+    contracts = correct_ret_only_contract(contracts, method)
+
+    # 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]
+
+    determine_has_proc_contract!
+    determine_has_options_contract!
+
+    @pattern_match = false
+    @klass         = klass
+    @method        = method
+  end
+
+  def to_s
+    "#{args_contracts_to_s} => #{ret_contract_to_s}".gsub!("Contracts::Builtin::", "")
+  end
+
+  def [](*args, &blk)
+    call(*args, &blk)
+  end
+
+  def call(*args, &blk)
+    call_with(nil, *args, &blk)
+  end
+
+  # mark contract as pattern matching contract
+  def pattern_match!
+    @pattern_match = true
+  end
+
+  # Used to determine if contract is a pattern matching contract
+  def pattern_match?
+    @pattern_match
+  end
+
+  # Used to determine type of failure exception this contract should raise in case of failure
+  def failure_exception
+    return PatternMatchingError if pattern_match?
+    ParamContractError
+  end
+
+  private
+
+  # BEFORE
+  # [Contracts::Builtin::Num]
+  # AFTER:
+  # [{nil=>Contracts::Builtin::Num}]
+  def correct_ret_only_contract(contracts, method)
+    unless contracts.last.is_a?(Hash)
+      unless contracts.one?
+        raise %{
+          It looks like your contract for #{method.name} doesn't have a return
+          value. A contract should be written as `Contract arg1, arg2 =>
+          return_value`.
+        }.strip
+      end
+      contracts = [nil => contracts[-1]]
+    end
+    contracts
+  end
+
+  def splat_args_contract_index
+    @splat_args_contract_index ||= args_contracts.index do |contract|
+      contract.is_a?(Contracts::SplatArgs)
+    end
+  end
+
+  def args_validators
+    @args_validators ||= args_contracts.map do |contract|
+      Contract.make_validator(contract)
+    end
+  end
+
+  def ret_validator
+    @ret_validator ||= Contract.make_validator(ret_contract)
+  end
+
+  def determine_has_proc_contract!
+    @has_proc_contract = kinda_proc?(args_contracts.last)
+  end
+
+  def determine_has_options_contract!
+    relevant_contract     = (@has_proc_contract ? args_contracts[-2] : args_contracts[-1])
+    @has_options_contract = kinda_hash?(relevant_contract)
+  end
+
+  def args_contracts_to_s
+    args_contracts.map { |c| pretty_contract(c) }.join(", ")
+  end
+
+  def ret_contract_to_s
+    pretty_contract(ret_contract)
+  end
+
+  def pretty_contract(c)
+    return c.name if c.is_a?(Class)
+    c.class.name
+  end
+
+  def kinda_hash?(v)
+    v.is_a?(Hash) || v.is_a?(Contracts::Builtin::KeywordArgs)
+  end
+
+  def kinda_proc?(v)
+    is_a_proc        = v.is_a?(Class) && (v <= Proc || v <= Method)
+    maybe_a_proc     = v.is_a?(Contracts::Maybe) && v.include_proc?
+    is_func_contract = v.is_a?(Contracts::Func)
+
+    (is_a_proc || maybe_a_proc || is_func_contract)
+  end
+end

data/lib/contracts/contract/call_with.rb

@@ -0,0 +1,119 @@
+module Contracts
+  module CallWith
+    SILENT_FAILURE = "silent_failure".freeze
+    def call_with(this, *args, &blk)
+      args << blk if blk
+
+      nil_block_appended = maybe_append_block!(args, blk)
+      maybe_append_options!(args, blk)
+
+      return if SILENT_FAILURE == catch(:return) do
+        args_validator.validate_args_before_splat!(args)
+      end
+
+      return if SILENT_FAILURE == catch(:return) do
+        args_validator.validate_splat_args_and_after!(args)
+      end
+
+      handle_result(this, args, blk, nil_block_appended)
+    end
+
+    private
+
+    def handle_result(this, args, blk, nil_block_appended)
+      restore_args!(args, blk, nil_block_appended)
+      result = execute_args(this, args, blk)
+
+      validate_result(result)
+      verify_invariants!(this)
+      wrap_result_if_func(result)
+    end
+
+    def args_validator
+      @args_validator ||= Contracts::ArgsValidator.new(
+        klass: klass,
+        method: method,
+        contracts: self,
+        args_contracts: args_contracts,
+        args_validators: args_validators,
+        splat_args_contract_index: splat_args_contract_index
+      )
+    end
+
+    # Restore the args
+    # - if we put the block into args for validating
+    # - OR if we added a fake nil at the end because a block wasn't passed in.
+    def restore_args!(args, blk, nil_block_appended)
+      args.slice!(-1) if blk || nil_block_appended
+    end
+
+    def validate_result(result)
+      return if ret_validator.call(result)
+      Contract.failure_callback(
+        :arg          => result,
+        :contract     => ret_contract,
+        :class        => klass,
+        :method       => method,
+        :contracts    => self,
+        :return_value => true
+      )
+    end
+
+    def verify_invariants!(this)
+      return unless this.respond_to?(:verify_invariants!)
+      this.verify_invariants!(method)
+    end
+
+    def wrap_result_if_func(result)
+      return result unless ret_contract.is_a?(Contracts::Func)
+      Contract.new(klass, result, *ret_contract.contracts)
+    end
+
+    def execute_args(this, args, blk)
+      # a `call`-able method, like proc, block, lambda
+      return method.call(*args, &blk) if method.respond_to?(:call)
+
+      # original method name referrence
+      method.send_to(this, *args, &blk)
+    end
+
+    # Explicitly append blk=nil if nil != Proc contract violation anticipated
+    # 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.
+    #
+    # 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 && needs_more_args?(args)
+      args << nil
+      true
+    end
+
+    def needs_more_args?(args)
+      is_splat           = splat_args_contract_index
+      more_args_expected = args.size < args_contracts.size
+      (is_splat || more_args_expected)
+    end
+
+    # Explicitly append options={} if Hash contract is present
+    # Same thing for when we have named params but didn't pass any in.
+    # returns true if it appended {}
+    def maybe_append_options!(args, blk)
+      return unless @has_options_contract
+      return args.insert(-2, {}) if use_penultimate_contract?(args)
+      return args.insert(-1, {}) if use_last_contract?(args)
+    end
+
+    def use_last_contract?(args)
+      return if args[-1].is_a?(Hash)
+      kinda_hash?(args_contracts[-1])
+    end
+
+    def use_penultimate_contract?(args)
+      return if args[-2].is_a?(Hash)
+      kinda_hash?(args_contracts[-2])
+    end
+  end # end CallWith
+end

data/lib/contracts/contract/failure_callback.rb

@@ -0,0 +1,61 @@
+module Contracts
+  module FailureCallback
+    # 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 do |data|
+      msg = Contracts::ErrorFormatters.failure_msg(data)
+
+      # this failed on the return contract
+      raise ReturnContractError.new(msg, data) if data[:return_value]
+
+      # this failed for a param contract
+      raise data[:contracts].failure_exception.new(msg, data)
+    end
+
+    # Callback for when a contract fails. By default it raises
+    # an error and prints detailed info about the contract that
+    # failed. You can also monkeypatch this callback to do whatever
+    # you want...log the error, send you an email, print an error
+    # message, etc.
+    #
+    # Example of monkeypatching:
+    #
+    #   def Contract.failure_callback(data)
+    #     puts "You had an error!"
+    #     puts failure_msg(data)
+    #     exit
+    #   end
+    def failure_callback(data, use_pattern_matching = true)
+      if data[:contracts].pattern_match? && use_pattern_matching
+        return DEFAULT_FAILURE_CALLBACK.call(data)
+      end
+
+      fetch_failure_callback.call(data)
+    end
+
+    # Used to override failure_callback without monkeypatching.
+    #
+    # Takes: block parameter, that should accept one argument - data.
+    #
+    # Example usage:
+    #
+    #   Contract.override_failure_callback do |data|
+    #     puts "You had an error"
+    #     puts failure_msg(data)
+    #     exit
+    #   end
+    def override_failure_callback(&blk)
+      @failure_callback = blk
+    end
+
+    # Used to restore default failure callback
+    def restore_failure_callback
+      @failure_callback = DEFAULT_FAILURE_CALLBACK
+    end
+
+    def fetch_failure_callback
+      @failure_callback ||= DEFAULT_FAILURE_CALLBACK
+    end
+  end
+end

data/lib/contracts/{validators.rb → contract/validators.rb}

@@ -37,7 +37,7 @@ module Contracts
         end
       end,
 
-      Contracts::Args => lambda do |contract|
+      Contracts::SplatArgs => lambda do |contract|
         lambda do |arg|
           Contract.valid?(arg, contract.contract)
         end
@@ -84,20 +84,15 @@ module Contracts
     # don't have to go through this decision tree every time.
     # Seems silly but it saves us a bunch of time (4.3sec vs 5.2sec)
     def make_validator!(contract)
+      validator_strategies[validator_key(contract)].call(contract)
+    end
+
+    def validator_key(contract)
       klass = contract.class
-      key = if validator_strategies.key?(klass)
-              klass
-            else
-              if contract.respond_to? :valid?
-                :valid
-              elsif klass == Class || klass == Module
-                :class
-              else
-                :default
-              end
-            end
-
-      validator_strategies[key].call(contract)
+      return klass  if validator_strategies.key?(klass)
+      return :valid if contract.respond_to? :valid?
+      return :class if klass == Class || klass == Module
+      :default
     end
 
     def make_validator(contract)

data/lib/contracts/core.rb

@@ -14,37 +14,16 @@ module Contracts
       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
+          return "No contract for #{self}.#{funcname}" if contracts.nil?
+          "#{funcname} :: #{contracts[0]}"
         end
       end
 
-      # NOTE: Workaround for `defined?(super)` bug in ruby 1.9.2
-      # source: http://stackoverflow.com/a/11181685
-      # bug: https://bugs.ruby-lang.org/issues/6644
-      base.class_eval <<-RUBY
-        # TODO: deprecate
-        # Required when contracts are included in global scope
-        def Contract(*args)
-          if defined?(super)
-            super
-          else
-            self.class.Contract(*args)
-          end
-        end
-      RUBY
-
       base.class_eval do
         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
+          return "No contract for #{self.class}.#{funcname}" if contracts.nil?
+          "#{funcname} :: #{contracts[0]}"
         end
       end
     end

data/lib/contracts/decorators.rb

@@ -25,7 +25,7 @@ module Contracts
     class << self; attr_accessor :decorators; end
 
     def self.inherited(klass)
-      name = klass.name.gsub(/^./) { |m| m.downcase }
+      name = klass.name.gsub(/^./, &:downcase)
 
       return if name =~ /^[^A-Za-z_]/ || name =~ /[^0-9A-Za-z_]/
 

data/lib/contracts/engine/base.rb

@@ -88,12 +88,12 @@ module Contracts
       #
       # @return [Engine::Base or Engine::Eigenclass]
       def nearest_decorated_ancestor
-        current = klass
+        current        = klass
         current_engine = self
-        ancestors = current.ancestors[1..-1]
+        ancestors      = current.ancestors[1..-1]
 
         while current && current_engine && !current_engine.decorated_methods?
-          current = ancestors.shift
+          current        = ancestors.shift
           current_engine = Engine.fetch_from(current)
         end
 
@@ -109,8 +109,7 @@ module Contracts
       end
 
       # No-op because it is safe to add decorators to normal classes
-      def validate!
-      end
+      def validate!; end
 
       def pop_decorators
         decorators.tap { clear_decorators }

data/lib/contracts/engine/eigenclass.rb

@@ -20,15 +20,14 @@ module Contracts
         Target.new(eigenclass).apply(Eigenclass)
         eigenclass.extend(MethodDecorators)
         # FIXME; this should detect what user uses `include Contracts` or
-        # `include Contracts;;Core`
+        # `include Contracts::Core`
         eigenclass.send(:include, Contracts)
         Engine.fetch_from(owner).set_eigenclass_owner
         Engine.fetch_from(eigenclass)
       end
 
       # No-op for eigenclasses
-      def set_eigenclass_owner
-      end
+      def set_eigenclass_owner; end
 
       # Fetches just eigenclasses decorators
       def all_decorators
@@ -39,7 +38,7 @@ module Contracts
 
       # Fails when contracts are not included in owner class
       def validate!
-        fail ContractsNotIncluded unless owner?
+        raise ContractsNotIncluded unless owner?
       end
 
       def owner?