Module: Handshake::ClassMethods

Defined in:
lib/handshake.rb

Overview

This module contains methods that are mixed into any class that includes Handshake. They allow you to define constraints on that class and its methods. Subclasses will inherit the contracts and invariants of its superclass, but Handshake contracts currently can’t be mixed-in via a module.

This module defines three kinds of contracts: class invariants, method signature constraints, and more general method pre- and post-conditions. Invariants accept a block which should return a boolean. Pre- and post- conditions expect you to use assertions (all of Test::Unit’s standard assertions are available) and will pass unless an assertion fails. Method signature contracts map inputs clauses to output clauses. A “clause” is defined as any object that implements the === method.

All method contracts are defined on the method defined immediately after their declaration unless a method name is specified. For example,

contract :foo, String => Integer

is equivalent to

contract String => Integer
def foo ...

Method signature contracts

contract String => Integer
contract [ String, 1..5, [ Integer ], Block ] => [ String, String ]
contract clause("must equal 'foo'") { |o| o == "foo" } => anything
contract Block(String => Integer) => Symbol

A method signature contract is defined as a mapping from valid inputs to to valid outputs. A clause here is any object which implements the === method. Classes, ranges, regexes, and other useful objects are thus all valid values for a method signature contract.

Multiple arguments are specified as an array. To specify that a method accepts varargs, define a nested array as the last or second-to-last item in the array. To specify that a method accepts a block, use the Block clause, which accepts a method signature hash as an argument, as above. To specify that a method should accept a block, but that the block should be unchecked, simply use Block instead of Block(… => …).

New clauses may be created easily with the Handshake::ClauseMethods#clause method. Handshake::ClauseMethods also provides a number of useful contract combinators for specifying rich input and output contracts.

Contract-checked accessors

contract_reader :foo => String, :bar => Integer
contract_writer ...
contract_accessor ...

Defines contract-checked accessors. Method names and clauses are specified in a hash. Hash values are any valid clause.

Invariants

invariant(optional_message) { returns true }

Aliased as always. Has access to instance variables and methods of object but calls to same are unchecked.

Pre/post-conditions

before(optional_message) { |arg1, ...| assert condition }
after(optional_message)  { |arg1, ..., returned| assert condition }
around(optional_message) { |arg1, ...| assert condition }

Check a set of conditions, using assertions, before and after method invocation. before and after are aliased as requires and ensures respectively. around currently throws a block argument warning; this should be fixed soon. Same scope rules as invariants, so you can check instance variables and local methods. All Test::Unit::Assertions are available for use, but any such AssertionFailed errors encountered are re-raised by Handshake as Handshake::AssertionFailed errors to avoid confusion with test case execution.

Instance Method Summary collapse

Instance Method Details

#===(other) ⇒ Object

In order for contract clauses to work in conjunction with Handshake proxy objects, the === method must be redefined in terms of is_a?.



165
166
167
 
# File 'lib/handshake.rb', line 165

def ===(other)
  other.is_a? self
end

#after(meth_or_mesg = nil, mesg = nil, &block) ⇒ Object Also known as: ensures

Specify a postcondition.



188
189
190
 
# File 'lib/handshake.rb', line 188

def after(meth_or_mesg=nil, mesg=nil, &block)
  condition(:after, meth_or_mesg, mesg, &block)
end

#around(meth_or_mesg = nil, mesg = nil, &block) ⇒ Object

Specify a bothcondition.



194
195
196
 
# File 'lib/handshake.rb', line 194

def around(meth_or_mesg=nil, mesg=nil, &block)
  condition(:around, meth_or_mesg, mesg, &block)
end

#before(meth_or_mesg = nil, mesg = nil, &block) ⇒ Object Also known as: requires

Specify a precondition.



182
183
184
 
# File 'lib/handshake.rb', line 182

def before(meth_or_mesg=nil, mesg=nil, &block)
  condition(:before, meth_or_mesg, mesg, &block)
end

#contract(meth_or_hash, contract_hash = nil) ⇒ Object

Specify an argument contract, with argument clauses on one side of the hash arrow and returned values on the other. Each clause must implement the === method or have been created with the assert method. This method should generally not be called directly.



173
174
175
176
177
178
179
 
# File 'lib/handshake.rb', line 173

def contract(meth_or_hash, contract_hash=nil)
  if meth_or_hash.is_a? Hash
    defer :contract, meth_or_hash
  else
    define_contract(meth_or_hash, contract_hash)
  end
end

#contract_accessor(meth_to_clause) ⇒ Object

Defines contract-checked attribute accessors for the given hash of method name to clause.



235
236
237
238
 
# File 'lib/handshake.rb', line 235

def contract_accessor(meth_to_clause)
  contract_reader meth_to_clause
  contract_writer meth_to_clause
end

#contract_defined?(method) ⇒ Boolean

Returns true if a contract is defined for the named method.

Returns:

  • (Boolean) 


211
212
213
 
# File 'lib/handshake.rb', line 211

def contract_defined?(method)
  method_contracts.has_key?(method)
end

#contract_for(method) ⇒ Object

Returns the MethodContract for the given method name. Side effect: creates one if none defined.



200
201
202
203
204
205
206
207
208
 
# File 'lib/handshake.rb', line 200

def contract_for(method)
  if contract_defined?(method)
    method_contracts[method]
  else
    contract = MethodContract.new("#{self}##{method}")
    write_inheritable_hash :method_contracts, { method => contract }
    contract
  end
end

#contract_reader(meth_to_clause) ⇒ Object

Defines contract-checked attribute readers with the given hash of method name to clause.



217
218
219
220
221
222
 
# File 'lib/handshake.rb', line 217

def contract_reader(meth_to_clause)
  attr_reader(*(meth_to_clause.keys))
  meth_to_clause.each do |meth, cls|
    contract meth, nil => cls
  end
end

#contract_writer(meth_to_clause) ⇒ Object

Defines contract-checked attribute writers with the given hash of method name to clause.



226
227
228
229
230
231
 
# File 'lib/handshake.rb', line 226

def contract_writer(meth_to_clause)
  attr_writer(*(meth_to_clause.keys))
  meth_to_clause.each do |meth, cls|
    contract "#{meth}=".to_sym, cls => anything
  end
end

#invariant(mesg = nil, &block) ⇒ Object Also known as: always

Specify an invariant, with a block and an optional error message.



157
158
159
160
 
# File 'lib/handshake.rb', line 157

def invariant(mesg=nil, &block) # :yields:
  write_inheritable_array(:invariants, [ Invariant.new(mesg, &block) ] )
  nil
end

#method_added(meth_name) ⇒ Object

Callback from method add event. If a previous method contract declaration was deferred, complete it now with the name of the newly- added method.



243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/handshake.rb', line 243

def method_added(meth_name)
  @deferred ||= {}
  unless @deferred.empty?
    @deferred.each do |k, v|
      case k
      when :before, :after, :around
        define_condition meth_name, k, v
      when :contract
        define_contract meth_name, v
      end
    end
    @deferred.clear
  end
end