contracts-lite 0.14.0

data/lib/contracts/error_formatter.rb

@@ -0,0 +1,121 @@
+module Contracts
+  class ErrorFormatters
+    def self.failure_msg(data)
+      class_for(data).new(data).message
+    end
+
+    def self.class_for(data)
+      return Contracts::KeywordArgsErrorFormatter if keyword_args?(data)
+      DefaultErrorFormatter
+    end
+
+    def self.keyword_args?(data)
+      data[:contract].is_a?(Contracts::Builtin::KeywordArgs) && data[:arg].is_a?(Hash)
+    end
+  end
+
+  class DefaultErrorFormatter
+    attr_accessor :data
+    def initialize(data)
+      @data = data
+    end
+
+    def message
+      %{#{header}
+        Expected: #{expected},
+        Actual: #{data[:arg].inspect}
+        Value guarded in: #{data[:class]}::#{method_name}
+        With Contract: #{data[:contracts]}
+        At: #{position} }
+    end
+
+    private
+
+    def header
+      if data[:return_value]
+        "Contract violation for return value:"
+      else
+        "Contract violation for argument #{data[:arg_pos]} of #{data[:total_args]}:"
+      end
+    end
+
+    def expected
+      Contracts::Formatters::Expected.new(data[:contract]).contract
+    end
+
+    def position
+      Contracts::Support.method_position(data[:method])
+    end
+
+    def method_name
+      Contracts::Support.method_name(data[:method])
+    end
+  end
+
+  class KeywordArgsErrorFormatter < DefaultErrorFormatter
+    def message
+      s = []
+      s << "#{header}"
+      s << "        Expected: #{expected}"
+      s << "        Actual: #{data[:arg].inspect}"
+      s << "        Missing Contract: #{missing_contract_info}" unless missing_contract_info.empty?
+      s << "        Invalid Args: #{invalid_args_info}"         unless invalid_args_info.empty?
+      s << "        Missing Args: #{missing_args_info}"         unless missing_args_info.empty?
+      s << "        Value guarded in: #{data[:class]}::#{method_name}"
+      s << "        With Contract: #{data[:contracts]}"
+      s << "        At: #{position} "
+
+      s.join("\n")
+    end
+
+    private
+
+    def missing_args_info
+      @missing_args_info ||= begin
+        missing_keys = contract_options.keys - arg.keys
+        contract_options.select do |key, _|
+          missing_keys.include?(key)
+        end
+      end
+    end
+
+    def missing_contract_info
+      @missing_contract_info ||= begin
+        contract_keys = contract_options.keys
+        arg.select { |key, _| !contract_keys.include?(key) }
+      end
+    end
+
+    def invalid_args_info
+      @invalid_args_info ||= begin
+        invalid_keys = []
+        arg.each do |key, value|
+          contract = contract_options[key]
+          next unless contract
+          invalid_keys.push(key) unless check_contract(contract, value)
+        end
+        invalid_keys.map do |key|
+          {key => arg[key], :contract => contract_options[key] }
+        end
+      end
+    end
+
+    def check_contract(contract, value)
+      if contract.respond_to?(:valid?)
+        contract.valid?(value)
+      else
+        value.is_a?(contract)
+      end
+    rescue
+      false
+    end
+
+    def contract_options
+      @contract_options ||= data[:contract].send(:options)
+    end
+
+    def arg
+      data[:arg]
+    end
+  end
+end

data/lib/contracts/errors.rb

@@ -0,0 +1,71 @@
+# @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
+
+class ParamContractError < ContractError
+end
+
+class ReturnContractError < ContractError
+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
+
+# Base invariant violation error
+class InvariantError < StandardError
+  def to_contract_error
+    self
+  end
+end
+
+module Contracts
+  # Error issued when user haven't included Contracts in original class but used Contract definition in singleton class
+  #
+  # Provides useful description for user of the gem and an example of correct usage.
+  class ContractsNotIncluded < TypeError
+    DEFAULT_MESSAGE = %{In order to use contracts in singleton class, please include Contracts module in original class
+    Example:
+
+    ```ruby
+    class Example
+      include Contracts  # this line is required
+      class << self
+        # you can use `Contract` definition here now
+      end
+    end
+    ```}
+
+    attr_reader :message
+    alias_method :to_s, :message
+
+    def initialize(message = DEFAULT_MESSAGE)
+      @message = message
+    end
+  end
+end

data/lib/contracts/formatters.rb

@@ -0,0 +1,134 @@
+module Contracts
+  # A namespace for classes related to formatting.
+  module Formatters
+    # Used to format contracts for the `Expected:` field of error output.
+    class Expected
+      # @param full [Boolean] if false only unique `to_s` values will be output,
+      #   non unique values become empty string.
+      def initialize(contract, full = true)
+        @contract, @full = contract, full
+      end
+
+      # Formats any type of Contract.
+      def contract(contract = @contract)
+        if contract.is_a?(Hash)
+          hash_contract(contract)
+        elsif contract.is_a?(Array)
+          array_contract(contract)
+        else
+          InspectWrapper.create(contract, @full)
+        end
+      end
+
+      # Formats Hash contracts.
+      def hash_contract(hash)
+        @full = true # Complex values output completely, overriding @full
+        hash.inject({}) do |repr, (k, v)|
+          repr.merge(k => InspectWrapper.create(contract(v), @full))
+        end.inspect
+      end
+
+      # Formats Array contracts.
+      def array_contract(array)
+        @full = true
+        array.map { |v| InspectWrapper.create(contract(v), @full) }.inspect
+      end
+    end
+
+    # A wrapper class to produce correct inspect behaviour for different
+    # contract values - constants, Class contracts, instance contracts etc.
+    module InspectWrapper
+      # InspectWrapper is a factory, will never be an instance
+      # @return [ClassInspectWrapper, ObjectInspectWrapper]
+      def self.create(value, full = true)
+        if value.class == Class
+          ClassInspectWrapper
+        else
+          ObjectInspectWrapper
+        end.new(value, full)
+      end
+
+      # @param full [Boolean] if false only unique `to_s` values will be output,
+      #   non unique values become empty string.
+      def initialize(value, full)
+        @value, @full = value, full
+      end
+
+      # Inspect different types of contract values.
+      # Contracts module prefix will be removed from classes.
+      # Custom to_s messages will be wrapped in round brackets to differentiate
+      # from standard Strings.
+      # Primitive values e.g. 42, true, nil will be left alone.
+      def inspect
+        return "" unless full?
+        return @value.inspect if empty_val?
+        return @value.to_s if plain?
+        return delim(@value.to_s) if useful_to_s?
+        useful_inspect
+      end
+
+      def delim(value)
+        @full ? "(#{value})" : "#{value}"
+      end
+
+      # Eliminates eronious quotes in output that plain inspect includes.
+      def to_s
+        inspect
+      end
+
+      private
+
+      def empty_val?
+        @value.nil? || @value == ""
+      end
+
+      def full?
+        @full ||
+          @value.is_a?(Hash) || @value.is_a?(Array) ||
+          (!plain? && useful_to_s?)
+      end
+
+      def plain?
+        # Not a type of contract that can have a custom to_s defined
+        !@value.is_a?(Builtin::CallableClass) && @value.class != Class
+      end
+
+      def useful_to_s?
+        # Useless to_s value or no custom to_s behavious defined
+        !empty_to_s? && custom_to_s?
+      end
+
+      def empty_to_s?
+        @value.to_s.empty?
+      end
+
+      def strip_prefix(val)
+        val.gsub(/^Contracts::Builtin::/, "")
+      end
+    end
+
+    class ClassInspectWrapper
+      include InspectWrapper
+
+      def custom_to_s?
+        @value.to_s != @value.name
+      end
+
+      def useful_inspect
+        strip_prefix(empty_to_s? ? @value.name : @value.inspect)
+      end
+    end
+
+    class ObjectInspectWrapper
+      include InspectWrapper
+
+      def custom_to_s?
+        !@value.to_s.match(/#\<\w+:.+\>/)
+      end
+
+      def useful_inspect
+        strip_prefix(empty_to_s? ? @value.class.name : @value.inspect)
+      end
+    end
+  end
+end

data/lib/contracts/invariants.rb

@@ -0,0 +1,68 @@
+module Contracts
+  module Invariants
+    def self.included(base)
+      common base
+    end
+
+    def self.extended(base)
+      common base
+    end
+
+    def self.common(base)
+      return if base.respond_to?(:Invariant)
+
+      base.extend(InvariantExtension)
+    end
+
+    def verify_invariants!(method)
+      return unless self.class.respond_to?(:invariants)
+
+      self.class.invariants.each do |invariant|
+        invariant.check_on(self, method)
+      end
+    end
+
+    module InvariantExtension
+      def invariant(name, &condition)
+        return if ENV["NO_CONTRACTS"]
+
+        invariants << Invariant.new(self, name, &condition)
+      end
+
+      def invariants
+        @invariants ||= []
+      end
+    end
+
+    class Invariant
+      def initialize(klass, name, &condition)
+        @klass, @name, @condition = klass, name, condition
+      end
+
+      def expected
+        "#{@name} condition to be true"
+      end
+
+      def check_on(target, method)
+        return if target.instance_eval(&@condition)
+
+        self.class.failure_callback(:expected => expected,
+                                    :actual => false,
+                                    :target => target,
+                                    :method => method)
+      end
+
+      def self.failure_callback(data)
+        fail InvariantError, failure_msg(data)
+      end
+
+      def self.failure_msg(data)
+        %{Invariant violation:
+            Expected: #{data[:expected]}
+            Actual: #{data[:actual]}
+            Value guarded in: #{data[:target].class}::#{Support.method_name(data[:method])}
+            At: #{Support.method_position(data[:method])}}
+      end
+    end
+  end
+end

data/lib/contracts/method_handler.rb

@@ -0,0 +1,195 @@
+module Contracts
+  # Handles class and instance methods addition
+  # Represents single such method
+  class MethodHandler
+    METHOD_REFERENCE_FACTORY = {
+      :class_methods => SingletonMethodReference,
+      :instance_methods => MethodReference
+    }
+
+    RAW_METHOD_STRATEGY = {
+      :class_methods => lambda { |target, name| target.method(name) },
+      :instance_methods => lambda { |target, name| target.instance_method(name) }
+    }
+
+    # Creates new instance of MethodHandler
+    #
+    # @param [Symbol] method_name
+    # @param [Bool] is_class_method
+    # @param [Class] target - class that method got added to
+    def initialize(method_name, is_class_method, target)
+      @method_name = method_name
+      @is_class_method = is_class_method
+      @target = target
+    end
+
+    # Handles method addition
+    def handle
+      return unless engine?
+      return if decorators.empty?
+
+      validate_decorators!
+      validate_pattern_matching!
+
+      engine.add_method_decorator(method_type, method_name, decorator)
+      mark_pattern_matching_decorators
+      method_reference.make_alias(target)
+      redefine_method
+    end
+
+    private
+
+    attr_reader :method_name, :is_class_method, :target
+
+    def engine?
+      Engine.applied?(target)
+    end
+
+    def engine
+      Engine.fetch_from(target)
+    end
+
+    def decorators
+      @_decorators ||= engine.all_decorators
+    end
+
+    def method_type
+      @_method_type ||= is_class_method ? :class_methods : :instance_methods
+    end
+    # _method_type is required for assigning it to local variable with
+    # the same name. See: #redefine_method
+    alias_method :_method_type, :method_type
+
+    def method_reference
+      @_method_reference ||= METHOD_REFERENCE_FACTORY[method_type].new(method_name, raw_method)
+    end
+
+    def raw_method
+      RAW_METHOD_STRATEGY[method_type].call(target, method_name)
+    end
+
+    def ignore_decorators?
+      ENV["NO_CONTRACTS"] && !pattern_matching?
+    end
+
+    def decorated_methods
+      @_decorated_methods ||= engine.decorated_methods_for(method_type, method_name)
+    end
+
+    def pattern_matching?
+      return @_pattern_matching if defined?(@_pattern_matching)
+      @_pattern_matching = decorated_methods.any? { |x| x.method != method_reference }
+    end
+
+    def mark_pattern_matching_decorators
+      return unless pattern_matching?
+      decorated_methods.each(&:pattern_match!)
+    end
+
+    def decorator
+      @_decorator ||= decorator_class.new(target, method_reference, *decorator_args)
+    end
+
+    def decorator_class
+      decorators.first[0]
+    end
+
+    def decorator_args
+      decorators.first[1]
+    end
+
+    def redefine_method
+      return if ignore_decorators?
+
+      # Those are required for instance_eval to be able to refer them
+      name = method_name
+      method_type = _method_type
+      current_engine = engine
+
+      # We are gonna redefine original method here
+      method_reference.make_definition(target) do |*args, &blk|
+        engine = current_engine.nearest_decorated_ancestor
+
+        # If we weren't able to find any ancestor that has decorated methods
+        # FIXME : this looks like untested code (commenting it out doesn't make specs red)
+        unless engine
+          fail "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
+
+        # Fetch decorated methods out of the contracts engine
+        decorated_methods = engine.decorated_methods_for(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 failure_exception, we move to the next
+        # function. Otherwise we return the result.
+        # If we run out of functions, we raise the last error, but
+        # convert it to_contract_error.
+        success = false
+        i = 0
+        result = nil
+        expected_error = decorated_methods[0].failure_exception
+
+        until success
+          decorated_method = decorated_methods[i]
+          i += 1
+          begin
+            success = true
+            result = decorated_method.call_with(self, *args, &blk)
+          rescue expected_error => error
+            success = false
+            unless decorated_methods[i]
+              begin
+                ::Contract.failure_callback(error.data, false)
+              rescue expected_error => final_error
+                raise final_error.to_contract_error
+              end
+            end
+          end
+        end
+
+        # Return the result of successfully called method
+        result
+      end
+    end
+
+    def validate_decorators!
+      return if decorators.size == 1
+
+      fail %{
+Oops, it looks like method '#{name}' has multiple contracts:
+#{decorators.map { |x| x[1][0].inspect }.join("\n")}
+
+Did you accidentally put more than one contract on a single function, like so?
+
+Contract String => String
+Contract Num => String
+def foo x
+end
+
+If you did NOT, then you have probably discovered a bug in this library.
+Please file it along with the relevant code at:
+https://github.com/egonSchiele/contracts.ruby/issues
+      }
+    end
+
+    def validate_pattern_matching!
+      new_args_contract = decorator.args_contracts
+      matched = decorated_methods.select do |contract|
+        contract.args_contracts == new_args_contract
+      end
+
+      return if matched.empty?
+
+      fail ContractError.new(%{
+It looks like you are trying to use pattern-matching, but
+multiple definitions for function '#{method_name}' have the same
+contract for input parameters:
+
+#{(matched + [decorator]).map(&:to_s).join("\n")}
+
+Each definition needs to have a different contract for the parameters.
+      }, {})
+    end
+  end
+end