Class: Contract
- Inherits:
-
Contracts::Decorator
- Object
- Contracts::Decorator
- Contract
- Extended by:
- Contracts::Validators
- Includes:
- Contracts::CallWith
- Defined in:
- lib/contracts.rb
Overview
This is the main Contract class. When you write a new contract, you’ll write it as:
Contract [contract names] => return_value
This class also provides useful callbacks and a validation method.
For #make_validator and related logic see file lib/contracts/validators.rb For #call_with and related logic see file lib/contracts/call_with.rb
Constant Summary collapse
- DEFAULT_FAILURE_CALLBACK =
Default implementation of failure_callback. Provided as a block to be able to monkey patch #failure_callback only temporary and then switch it back. First important usage - for specs.
proc do |data| if data[:return_value] # this failed on the return contract fail ReturnContractError.new(failure_msg(data), data) else # this failed for a param contract fail data[:contracts].failure_exception.new(failure_msg(data), data) end end
Constants included from Contracts::Validators
Contracts::Validators::DEFAULT_VALIDATOR_STRATEGIES
Instance Attribute Summary collapse
-
#args_contracts ⇒ Object
readonly
Returns the value of attribute args_contracts.
-
#klass ⇒ Object
readonly
Returns the value of attribute klass.
-
#method ⇒ Object
readonly
Returns the value of attribute method.
-
#ret_contract ⇒ Object
readonly
Returns the value of attribute ret_contract.
Class Method Summary collapse
-
.failure_callback(data, use_pattern_matching: true) ⇒ Object
Callback for when a contract fails.
-
.failure_msg(data) ⇒ Object
Given a hash, prints out a failure message.
- .fetch_failure_callback ⇒ Object
-
.override_failure_callback(&blk) ⇒ Object
Used to override failure_callback without monkeypatching.
-
.restore_failure_callback ⇒ Object
Used to restore default failure callback.
-
.valid?(arg, contract) ⇒ Boolean
Used to verify if an argument satisfies a contract.
Instance Method Summary collapse
- #[](*args, &blk) ⇒ Object
- #call(*args, &blk) ⇒ Object
-
#failure_exception ⇒ Object
Used to determine type of failure exception this contract should raise in case of failure.
-
#initialize(klass, method, *contracts) ⇒ Contract
constructor
A new instance of Contract.
-
#maybe_append_block!(args, blk) ⇒ Object
a better way to handle this might be to take this into account before throwing a “mismatched # of args” error.
-
#maybe_append_options!(args, kargs, blk) ⇒ Object
Same thing for when we have named params but didn’t pass any in.
-
#pattern_match! ⇒ Object
Used internally to mark contract as pattern matching contract.
-
#pattern_match? ⇒ Boolean
Used to determine if contract is a pattern matching contract.
- #pretty_contract(contract) ⇒ Object
- #to_s ⇒ Object
Methods included from Contracts::Validators
clean_memoized_validators, make_validator, make_validator!, memoized_validators, override_validator, reset_validators, restore_validators, validator_strategies
Methods included from Contracts::CallWith
Methods inherited from Contracts::Decorator
Constructor Details
#initialize(klass, method, *contracts) ⇒ Contract
Returns a new instance of Contract.
57 58 59 60 61 62 63 64 65 66 67 68 69 70 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 |
# File 'lib/contracts.rb', line 57 def initialize(klass, method, *contracts) super(klass, method) unless contracts.last.is_a?(Hash) unless contracts.one? fail %{ It looks like your contract for #{method.name} doesn't have a return value. A contract should be written as `Contract arg1, arg2 => return_value`. }.strip end contracts = [nil => contracts[-1]] end # internally we just convert that return value syntax back to an array @args_contracts = contracts[0, contracts.size - 1] + contracts[-1].keys @ret_contract = contracts[-1].values[0] @args_validators = args_contracts.map do |contract| Contract.make_validator(contract) end @args_contract_index = args_contracts.index do |contract| contract.is_a? Contracts::Args end @ret_validator = Contract.make_validator(ret_contract) @pattern_match = false # == @has_proc_contract last_contract = args_contracts.last is_a_proc = last_contract.is_a?(Class) && (last_contract <= Proc || last_contract <= Method) maybe_a_proc = last_contract.is_a?(Contracts::Maybe) && last_contract.include_proc? @has_proc_contract = is_a_proc || maybe_a_proc || last_contract.is_a?(Contracts::Func) # ==== # == @has_options_contract last_contract = args_contracts.last penultimate_contract = args_contracts[-2] @has_options_contract = if @has_proc_contract penultimate_contract.is_a?(Contracts::Builtin::KeywordArgs) else last_contract.is_a?(Contracts::Builtin::KeywordArgs) end # === @klass, @method = klass, method end |
Instance Attribute Details
#args_contracts ⇒ Object (readonly)
Returns the value of attribute args_contracts.
55 56 57 |
# File 'lib/contracts.rb', line 55 def args_contracts @args_contracts end |
#klass ⇒ Object (readonly)
Returns the value of attribute klass.
55 56 57 |
# File 'lib/contracts.rb', line 55 def klass @klass end |
#method ⇒ Object (readonly)
Returns the value of attribute method.
55 56 57 |
# File 'lib/contracts.rb', line 55 def method @method end |
#ret_contract ⇒ Object (readonly)
Returns the value of attribute ret_contract.
55 56 57 |
# File 'lib/contracts.rb', line 55 def ret_contract @ret_contract end |
Class Method Details
.failure_callback(data, use_pattern_matching: true) ⇒ Object
Callback for when a contract fails. By default it raises an error and prints detailed info about the contract that failed. You can also monkeypatch this callback to do whatever you want…log the error, send you an email, print an error message, etc.
Example of monkeypatching:
def Contract.failure_callback(data)
puts "You had an error!"
puts failure_msg(data)
exit
end
192 193 194 195 196 197 198 |
# File 'lib/contracts.rb', line 192 def self.failure_callback(data, use_pattern_matching: true) if data[:contracts].pattern_match? && use_pattern_matching return DEFAULT_FAILURE_CALLBACK.call(data) end fetch_failure_callback.call(data) end |
.failure_msg(data) ⇒ Object
Given a hash, prints out a failure message. This function is used by the default #failure_callback method and uses the hash passed into the failure_callback method.
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 |
# File 'lib/contracts.rb', line 122 def self.failure_msg(data) indent_amount = 8 method_name = Contracts::Support.method_name(data[:method]) # Header header = if data[:return_value] "Contract violation for return value:" else "Contract violation for argument #{data[:arg_pos]} of #{data[:total_args]}:" end # Expected expected_prefix = "Expected: " expected_value = Contracts::Support.indent_string( Contracts::Formatters::Expected.new(data[:contract]).contract.pretty_inspect, expected_prefix.length, ).strip expected_line = "#{expected_prefix}#{expected_value}," # Actual actual_prefix = "Actual: " actual_value = Contracts::Support.indent_string( data[:arg].pretty_inspect, actual_prefix.length, ).strip actual_line = actual_prefix + actual_value # Value guarded in value_prefix = "Value guarded in: " value_value = "#{data[:class]}::#{method_name}" value_line = value_prefix + value_value # Contract contract_prefix = "With Contract: " contract_value = data[:contracts].to_s contract_line = contract_prefix + contract_value # Position position_prefix = "At: " position_value = Contracts::Support.method_position(data[:method]) position_line = position_prefix + position_value [ header, Contracts::Support.indent_string( [ expected_line, actual_line, value_line, contract_line, position_line, ].join("\n"), indent_amount, ), ].join("\n") end |
.fetch_failure_callback ⇒ Object
220 221 222 |
# File 'lib/contracts.rb', line 220 def self.fetch_failure_callback @failure_callback ||= DEFAULT_FAILURE_CALLBACK end |
.override_failure_callback(&blk) ⇒ Object
Used to override failure_callback without monkeypatching.
Takes: block parameter, that should accept one argument - data.
Example usage:
Contract.override_failure_callback do |data|
puts "You had an error"
puts failure_msg(data)
exit
end
211 212 213 |
# File 'lib/contracts.rb', line 211 def self.override_failure_callback(&blk) @failure_callback = blk end |
.restore_failure_callback ⇒ Object
Used to restore default failure callback
216 217 218 |
# File 'lib/contracts.rb', line 216 def self.restore_failure_callback @failure_callback = DEFAULT_FAILURE_CALLBACK end |
.valid?(arg, contract) ⇒ Boolean
Used to verify if an argument satisfies a contract.
Takes: an argument and a contract.
Returns: a tuple: [Boolean, metadata]. The boolean indicates whether the contract was valid or not. If it wasn’t, metadata contains some useful information about the failure.
231 232 233 |
# File 'lib/contracts.rb', line 231 def self.valid?(arg, contract) make_validator(contract)[arg] end |
Instance Method Details
#[](*args, &blk) ⇒ Object
235 236 237 |
# File 'lib/contracts.rb', line 235 def [](*args, &blk) call(*args, &blk) end |
#call(*args, &blk) ⇒ Object
239 240 241 |
# File 'lib/contracts.rb', line 239 def call(*args, &blk) call_with(nil, *args, &blk) end |
#failure_exception ⇒ Object
Used to determine type of failure exception this contract should raise in case of failure
272 273 274 275 276 277 278 |
# File 'lib/contracts.rb', line 272 def failure_exception if pattern_match? PatternMatchingError else ParamContractError end end |
#maybe_append_block!(args, blk) ⇒ Object
a better way to handle this might be to take this into account before throwing a “mismatched # of args” error. returns true if it appended nil
250 251 252 253 254 255 256 |
# File 'lib/contracts.rb', line 250 def maybe_append_block! args, blk return false unless @has_proc_contract && !blk && (@args_contract_index || args.size < args_contracts.size) args << nil true end |
#maybe_append_options!(args, kargs, blk) ⇒ Object
Same thing for when we have named params but didn’t pass any in. returns true if it appended nil
260 261 262 263 264 265 266 267 268 269 |
# File 'lib/contracts.rb', line 260 def args, kargs, blk return false unless @has_options_contract if @has_proc_contract && args_contracts[-2].is_a?(Contracts::Builtin::KeywordArgs) args.insert(-2, kargs) elsif args_contracts[-1].is_a?(Contracts::Builtin::KeywordArgs) args << kargs end true end |
#pattern_match! ⇒ Object
Used internally to mark contract as pattern matching contract
282 283 284 |
# File 'lib/contracts.rb', line 282 def pattern_match! @pattern_match = true end |
#pattern_match? ⇒ Boolean
Used to determine if contract is a pattern matching contract
287 288 289 |
# File 'lib/contracts.rb', line 287 def pattern_match? @pattern_match == true end |
#pretty_contract(contract) ⇒ Object
109 110 111 |
# File 'lib/contracts.rb', line 109 def pretty_contract contract contract.is_a?(Class) ? contract.name : contract.class.name end |
#to_s ⇒ Object
113 114 115 116 117 |
# File 'lib/contracts.rb', line 113 def to_s args = args_contracts.map { |c| pretty_contract(c) }.join(", ") ret = pretty_contract(ret_contract) ("#{args} => #{ret}").gsub("Contracts::Builtin::", "") end |