contracts 0.9 → 0.10

data/lib/contracts/engine.rb

@@ -0,0 +1,26 @@
+require "contracts/engine/base"
+require "contracts/engine/target"
+require "contracts/engine/eigenclass"
+
+require "forwardable"
+
+module Contracts
+  # Engine facade, normally you shouldn't refer internals of Engine
+  # module directly.
+  module Engine
+    class << self
+      extend Forwardable
+
+      # .apply(klass)      - enables contracts engine on klass
+      # .applied?(klass)   - returns true if klass has contracts engine
+      # .fetch_from(klass) - returns contracts engine for klass
+      def_delegators :base_engine, :apply, :applied?, :fetch_from
+
+      private
+
+      def base_engine
+        Base
+      end
+    end
+  end
+end

data/lib/contracts/engine/base.rb

@@ -0,0 +1,136 @@
+module Contracts
+  module Engine
+    # Contracts engine
+    class Base
+      # Enable contracts engine for klass
+      #
+      # @param [Class] klass - target class
+      def self.apply(klass)
+        Engine::Target.new(klass).apply
+      end
+
+      # Returns true if klass has contracts engine
+      #
+      # @param [Class] klass - target class
+      # @return [Bool]
+      def self.applied?(klass)
+        Engine::Target.new(klass).applied?
+      end
+
+      # Fetches contracts engine out of klass
+      #
+      # @param [Class] klass - target class
+      # @return [Engine::Base or Engine::Eigenclass]
+      def self.fetch_from(klass)
+        Engine::Target.new(klass).engine
+      end
+
+      # Creates new instance of contracts engine
+      #
+      # @param [Class] klass - class that owns this engine
+      def initialize(klass)
+        @klass = klass
+      end
+
+      # Adds provided decorator to the engine
+      # It validates that decorator can be added to this engine at the
+      # moment
+      #
+      # @param [Decorator:Class] decorator_class
+      # @param args - arguments for decorator
+      def decorate(decorator_class, *args)
+        validate!
+        decorators << [decorator_class, args]
+      end
+
+      # Sets eigenclass' owner to klass
+      def set_eigenclass_owner
+        eigenclass_engine.owner_class = klass
+      end
+
+      # Fetches all accumulated decorators (both this engine and
+      # corresponding eigenclass' engine)
+      # It clears all accumulated decorators
+      #
+      # @return [ArrayOf[Decorator]]
+      def all_decorators
+        pop_decorators + eigenclass_engine.all_decorators
+      end
+
+      # Fetches decorators of specified type for method with name
+      #
+      # @param [Or[:class_methods, :instance_methods]] type - method type
+      # @param [Symbol] name - method name
+      # @return [ArrayOf[Decorator]]
+      def decorated_methods_for(type, name)
+        Array(decorated_methods[type][name])
+      end
+
+      # Returns true if there are any decorated methods
+      #
+      # @return [Bool]
+      def decorated_methods?
+        !decorated_methods[:class_methods].empty? ||
+          !decorated_methods[:instance_methods].empty?
+      end
+
+      # Adds method decorator
+      #
+      # @param [Or[:class_methods, :instance_methods]] type - method type
+      # @param [Symbol] name - method name
+      # @param [Decorator] decorator - method decorator
+      def add_method_decorator(type, name, decorator)
+        decorated_methods[type][name] ||= []
+        decorated_methods[type][name] << decorator
+      end
+
+      # Returns nearest ancestor's engine that has decorated methods
+      #
+      # @return [Engine::Base or Engine::Eigenclass]
+      def nearest_decorated_ancestor
+        current = klass
+        current_engine = self
+        ancestors = current.ancestors[1..-1]
+
+        while current && current_engine && !current_engine.decorated_methods?
+          current = ancestors.shift
+          current_engine = Engine.fetch_from(current)
+        end
+
+        current_engine
+      end
+
+      private
+
+      attr_reader :klass
+
+      def decorated_methods
+        @_decorated_methods ||= { :class_methods => {}, :instance_methods => {} }
+      end
+
+      # No-op because it is safe to add decorators to normal classes
+      def validate!
+      end
+
+      def pop_decorators
+        decorators.tap { clear_decorators }
+      end
+
+      def eigenclass
+        Support.eigenclass_of(klass)
+      end
+
+      def eigenclass_engine
+        Eigenclass.lift(eigenclass, klass)
+      end
+
+      def decorators
+        @_decorators ||= []
+      end
+
+      def clear_decorators
+        @_decorators = []
+      end
+    end
+  end
+end

data/lib/contracts/engine/eigenclass.rb

@@ -0,0 +1,46 @@
+module Contracts
+  module Engine
+    # Special case of contracts engine for eigenclasses
+    # We don't care about eigenclass of eigenclass at this point
+    class Eigenclass < Base
+      # Class that owns this eigenclass
+      attr_accessor :owner_class
+
+      # Automatically enables eigenclass engine if it is not
+      # Returns its engine
+      # NOTE: Required by jruby in 1.9 mode. Otherwise inherited
+      # eigenclasses don't have their engines
+      #
+      # @param [Class] eigenclass - class in question
+      # @param [Class] owner - owner of eigenclass
+      # @return [Engine::Eigenclass]
+      def self.lift(eigenclass, owner)
+        return Engine.fetch_from(eigenclass) if Engine.applied?(eigenclass)
+
+        Target.new(eigenclass).apply(Eigenclass)
+        Engine.fetch_from(owner).set_eigenclass_owner
+        Engine.fetch_from(eigenclass)
+      end
+
+      # No-op for eigenclasses
+      def set_eigenclass_owner
+      end
+
+      # Fetches just eigenclasses decorators
+      def all_decorators
+        pop_decorators
+      end
+
+      private
+
+      # Fails when contracts are not included in owner class
+      def validate!
+        fail ContractsNotIncluded unless owner?
+      end
+
+      def owner?
+        !!owner_class
+      end
+    end
+  end
+end

data/lib/contracts/engine/target.rb

@@ -0,0 +1,68 @@
+module Contracts
+  module Engine
+    # Represents class in question
+    class Target
+      # Creates new instance of Target
+      #
+      # @param [Class] target - class in question
+      def initialize(target)
+        @target = target
+      end
+
+      # Enable contracts engine for target
+      # - it is no-op if contracts engine is already enabled
+      # - it automatically enables contracts engine for its eigenclass
+      # - it sets owner class to target for its eigenclass
+      #
+      # @param [Engine::Base:Class] engine_class - type of engine to
+      #   enable (Base or Eigenclass)
+      def apply(engine_class = Base)
+        return if applied?
+
+        apply_to_eigenclass
+
+        eigenclass.class_eval do
+          define_method(:__contracts_engine) do
+            @__contracts_engine ||= engine_class.new(self)
+          end
+        end
+
+        engine.set_eigenclass_owner
+      end
+
+      # Returns true if target has contracts engine already
+      #
+      # @return [Bool]
+      def applied?
+        target.respond_to?(:__contracts_engine)
+      end
+
+      # Returns contracts engine of target
+      #
+      # @return [Engine::Base or Engine::Eigenclass]
+      def engine
+        applied? && target.__contracts_engine
+      end
+
+      private
+
+      attr_reader :target
+
+      def apply_to_eigenclass
+        return unless meaningless_eigenclass?
+
+        self.class.new(eigenclass).apply(Eigenclass)
+        eigenclass.extend(MethodDecorators)
+        eigenclass.send(:include, Contracts)
+      end
+
+      def eigenclass
+        Support.eigenclass_of(target)
+      end
+
+      def meaningless_eigenclass?
+        !Support.eigenclass?(target)
+      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