entitlements 0.1.8 → 0.2.0

data/lib/contracts-ruby3/lib/contracts/core.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Contracts
+  module Core
+    def self.included(base)
+      common(base)
+    end
+
+    def self.extended(base)
+      common(base)
+    end
+
+    def self.common(base)
+      base.extend(MethodDecorators)
+
+      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
+        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, __FILE__, __LINE__ + 1
+        # 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
+        end
+      end
+    end
+  end
+end

data/lib/contracts-ruby3/lib/contracts/decorators.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Contracts
+  module MethodDecorators
+    def self.extended(klass)
+      Engine.apply(klass)
+    end
+
+    def inherited(subclass)
+      Engine.fetch_from(subclass).set_eigenclass_owner
+      super
+    end
+
+    def method_added(name)
+      MethodHandler.new(name, false, self).handle
+      super
+    end
+
+    def singleton_method_added(name)
+      MethodHandler.new(name, true, self).handle
+      super
+    end
+  end
+
+  class Decorator
+    # an attr_accessor for a class variable:
+    class << self; attr_accessor :decorators; end
+
+    def self.inherited(klass)
+      super
+      name = klass.name.gsub(/^./) { |m| m.downcase }
+
+      return if name =~ /^[^A-Za-z_]/ || name =~ /[^0-9A-Za-z_]/
+
+      # the file and line parameters set the text for error messages
+      # make a new method that is the name of your decorator.
+      # that method accepts random args and a block.
+      # inside, `decorate` is called with those params.
+      MethodDecorators.module_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+        def #{klass}(*args, &blk)
+          ::Contracts::Engine.fetch_from(self).decorate(#{klass}, *args, &blk)
+        end
+      RUBY_EVAL
+    end
+
+    def initialize(klass, method)
+      @method = method
+    end
+  end
+end

data/lib/contracts-ruby3/lib/contracts/engine/base.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+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..]
+
+        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-ruby3/lib/contracts/engine/eigenclass.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+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)
+        eigenclass.extend(MethodDecorators)
+        # FIXME; this should detect what user uses `include Contracts` or
+        # `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
+
+      # 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-ruby3/lib/contracts/engine/target.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+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)
+        # FIXME; this should detect what user uses `include Contracts` or
+        # `include Contracts;;Core`
+        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-ruby3/lib/contracts/engine.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+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-ruby3/lib/contracts/errors.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# @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)
+      super
+      @message = message
+    end
+  end
+end

data/lib/contracts-ruby3/lib/contracts/formatters.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "pp"
+
+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)
+        case contract
+        when Hash
+          hash_contract(contract)
+        when Array
+          array_contract(contract)
+        else
+          InspectWrapper.create(contract, full: @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: @full))
+        end
+      end
+
+      # Formats Array contracts.
+      def array_contract(array)
+        @full = true
+        array.map { |v| InspectWrapper.create(contract(v), full: @full) }
+      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.instance_of?(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 behaviour 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-ruby3/lib/contracts/invariants.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+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