Module: Handshake

Defined in:
lib/handshake/version.rb,
lib/handshake/handshake.rb

Overview

A module for defining class and method contracts (as in design-by-contract programming). To use it in your code, include this module in a class. Note that when you do so, that class’s new method will be replaced. There are three different types of contracts you can specify on a class. See Handshake::ClassMethods for more documentation.

Defined Under Namespace

Modules: ClassMethods, ClauseMethods, InstanceMethods, VERSION Classes: AssertionFailed, Block, Clause, ContractError, ContractViolation, Invariant, MethodCondition, MethodContract, Proxy

Class Method Summary collapse

Class Method Details

.catch_contract(mesg = nil, &block) ⇒ Object

Catches any thrown :contract exception raised within the given block, appends the given message to the violation message, and re-raises the exception.



51
52
53
54
55
56
57
58
59
60
# File 'lib/handshake/handshake.rb', line 51

def Handshake.catch_contract(mesg=nil, &block) # :nodoc:
  violation = catch(:contract, &block)
  if violation.is_a?(Exception)
    # Re-raise the violation with the given message, ensuring that the
    # callback stack begins with the caller of this method rather than
    # this method.
    message = ( mesg.nil? ? "" : ( mesg + ": " ) ) + violation.message
    raise violation.class, message, caller
  end
end

.included(base) ⇒ Object

When Handshake is included in a class, that class’s new method is overridden to provide custom functionality. A proxy object, returned in place of the real object, filters all external method calls through any contracts that have been defined. <b>N.B.:<b> Handshake is designed to act as a barrier between an object and its callers. However, anything that takes place within that barrier is not checked. This means that Handshake is, at the moment, unable to enforce contracts on methods called only internally, notably private methods.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
# File 'lib/handshake/handshake.rb', line 71

def Handshake.included(base)
  base.extend(ClassMethods)
  base.extend(ClauseMethods)

  base.send(:include, Test::Unit::Assertions)
  base.send(:include, Handshake::InstanceMethods)

  base.class_inheritable_array :invariants
  base.write_inheritable_array :invariants, []

  base.class_inheritable_hash :method_contracts
  base.write_inheritable_hash :method_contracts, {}

  class << base
    alias :instantiate :new
    # Override the class-level new method of every class that includes
    # Contract and cause it to return a proxy object for the original.
    def new(*args, &block)
      if @non_instantiable
        raise ContractViolation, "This class has been marked as abstract and cannot be instantiated."
      end
      o = nil

      # Special case:  check invariants for constructor.
      Handshake.catch_contract("Contract violated in call to constructor of class #{self}") do
        if contract_defined? :initialize
          method_contracts[:initialize].check_accepts!(*args, &block)
        end
      end

      o = self.instantiate(*args, &block)

      Handshake.catch_contract("Invariant violated by constructor of class #{self}") do
        o.check_invariants!
      end

      raise ContractError, "Could not instantiate object" if o.nil?
      Proxy.new( o )
    end
  end
end