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
-
.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.
-
.included(base) ⇒ Object
When Handshake is included in a class, that class’s
new
method is overridden to provide custom functionality.
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. = ( mesg.nil? ? "" : ( mesg + ": " ) ) + violation. raise violation.class, , 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 |