<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Class: Contract</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Class</strong></td>
<td class="class-name-in-header">Contract</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../files/lib/contract/exception_rb.html">
lib/contract/exception.rb
</a>
<br />
<a href="../files/lib/contract/overrides_rb.html">
lib/contract/overrides.rb
</a>
<br />
<a href="../files/lib/contract/assertions_rb.html">
lib/contract/assertions.rb
</a>
<br />
<a href="../files/lib/contract/integration_rb.html">
lib/contract/integration.rb
</a>
<br />
<a href="../files/lib/contract_rb.html">
lib/contract.rb
</a>
<br />
</td>
</tr>
<tr class="top-aligned-row">
<td><strong>Parent:</strong></td>
<td>
Test::Unit::TestCase
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<p>
Represents a contract between Objects as a collection of test cases.
Objects are said to fulfill a contract if all test cases suceed. This is
useful for ensuring that Objects your code is getting behave in a way that
you expect them to behave so you can fail early or execute different logic
for Objects with different interfaces.
</p>
<p>
The tests of the test suite will be run on a copy of the tested Object so
you can safely test its behavior without having to fear data loss. By
default Contracts obtain deep copies of Objects by serializing and
unserializing them with Ruby’s <tt>Marshal</tt> functionality. This
will work in most cases but can fail for Objects containing unserializable
parts like Procs, Files or Sockets. In those cases it is currently of your
responsibility to provide a fitting implementation by overwriting the <a
href="Contract.html#M000006">Contract.deep_copy</a> method. In the future
the contract library might provide different implementations of it via
Ruby’s mixin mechanism.
</p>
</div>
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000006">deep_copy</a>
<a href="#M000003">enforce</a>
<a href="#M000002">fulfilled_by?</a>
<a href="#M000001">provides</a>
<a href="#M000004">test</a>
<a href="#M000005">test_all</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<div id="class-list">
<h3 class="section-bar">Classes and Modules</h3>
Module <a href="Contract/ContractException.html" class="link">Contract::ContractException</a><br />
Class <a href="Contract/ContractError.html" class="link">Contract::ContractError</a><br />
Class <a href="Contract/ContractMismatch.html" class="link">Contract::ContractMismatch</a><br />
</div>
<div id="constants-list">
<h3 class="section-bar">Constants</h3>
<div class="name-list">
<table summary="Constants">
<tr class="top-aligned-row context-row">
<td class="context-item-name">Version</td>
<td>=</td>
<td class="context-item-value">id.split(" ")[2].to_i</td>
<td width="3em"> </td>
<td class="context-item-desc">
The Version of the contract library you are using.
</td>
</tr>
</table>
</div>
</div>
<div id="aliases-list">
<h3 class="section-bar">External Aliases</h3>
<div class="name-list">
<table summary="aliases">
<tr class="top-aligned-row context-row">
<td class="context-item-name">check_signatures</td>
<td>-></td>
<td class="context-item-value">check_signatures?</td>
</tr>
<tr class="top-aligned-row context-row">
<td class="context-item-name">fulfilled_by?</td>
<td>-></td>
<td class="context-item-value">===</td>
</tr>
</table>
</div>
</div>
<div id="attribute-list">
<h3 class="section-bar">Attributes</h3>
<div class="name-list">
<table>
<tr class="top-aligned-row context-row">
<td class="context-item-name">check_signatures</td>
<td class="context-item-value"> [RW] </td>
<td class="context-item-desc">
Whether signatures should be checked. By default signatures are checked
only when the application is run in $DEBUG mode. (By specifying the -d
switch on the invocation of Ruby.)
<p>
Note: If you want to change this you need to do so before doing any
signature calls or it will not be applied.
</p>
</td>
</tr>
</table>
</div>
</div>
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Class methods</h3>
<div id="method-M000006" class="method-detail">
<a name="M000006"></a>
<div class="method-heading">
<a href="Contract.src/M000006.html" target="Code" class="method-signature"
onclick="popupCode('Contract.src/M000006.html');return false;">
<span class="method-name">deep_copy</span><span class="method-args">(object)</span>
</a>
</div>
<div class="method-description">
<p>
This method is used internally for getting a copy of Objects that the
contract is checked against. By default it uses Ruby’s
<tt>Marshal</tt> functionality for obtaining a copy, but this can fail if
the Object contains unserializable parts like Procs, Files or Sockets. It
is currently your responsibility to provide a fitting implementation of
this by overwriting the method in case the default implementation does not
work for you. In the future the contract library might offer different
implementations for this via Ruby’s mixin mechanism.
</p>
</div>
</div>
<div id="method-M000003" class="method-detail">
<a name="M000003"></a>
<div class="method-heading">
<a href="Contract.src/M000003.html" target="Code" class="method-signature"
onclick="popupCode('Contract.src/M000003.html');return false;">
<span class="method-name">enforce</span><span class="method-args">(object)</span>
</a>
</div>
<div class="method-description">
<p>
Enforces that object implements this contract. If it does not an Exception
will be raised. This is useful for example useful when you need to ensure
that the arguments given to a method fulfill a given contract.
</p>
</div>
</div>
<div id="method-M000002" class="method-detail">
<a name="M000002"></a>
<div class="method-heading">
<a href="Contract.src/M000002.html" target="Code" class="method-signature"
onclick="popupCode('Contract.src/M000002.html');return false;">
<span class="method-name">fulfilled_by?</span><span class="method-args">(object)</span>
</a>
</div>
<div class="method-description">
<p>
Returns true if the given object fulfills this contract. This is useful for
implementing dispatching mechanisms where you want to hit different code
branches based on whether an Object has one or another interface.
</p>
</div>
</div>
<div id="method-M000001" class="method-detail">
<a name="M000001"></a>
<div class="method-heading">
<a href="Contract.src/M000001.html" target="Code" class="method-signature"
onclick="popupCode('Contract.src/M000001.html');return false;">
<span class="method-name">provides</span><span class="method-args">(*symbols, &block)</span>
</a>
</div>
<div class="method-description">
<p>
Tests that the tested Object provides the specified methods with the
specified behavior.
</p>
<p>
This can be used like this:
</p>
<pre>
class ListContract < Contract
provides :size do
assert(@object.size >= 0, "#size should never be negative.")
end
provides :include?
provides :each do
count = 0
@object.each do |item|
assert(@object.include?(item),
"#each should only yield items that the list includes.")
count += 1
end
assert_equal(@object.size, count,
"#each should yield #size items.")
end
end
</pre>
</div>
</div>
<div id="method-M000004" class="method-detail">
<a name="M000004"></a>
<div class="method-heading">
<a href="Contract.src/M000004.html" target="Code" class="method-signature"
onclick="popupCode('Contract.src/M000004.html');return false;">
<span class="method-name">test</span><span class="method-args">(object, return_all = false)</span>
</a>
</div>
<div class="method-description">
<p>
Tests whether the given Object fulfils this contract.
</p>
<p>
Note: This will return the first reason for the Object not fulfilling the
contract or <tt>nil</tt> in case it fulfills it.
</p>
</div>
</div>
<div id="method-M000005" class="method-detail">
<a name="M000005"></a>
<div class="method-heading">
<a href="Contract.src/M000005.html" target="Code" class="method-signature"
onclick="popupCode('Contract.src/M000005.html');return false;">
<span class="method-name">test_all</span><span class="method-args">(object)</span>
</a>
</div>
<div class="method-description">
<p>
Same as <a href="Contract.html#M000004">Contract.test</a>, but will return
all reasons for the Object not fulfilling the contract in an Array or nil
in case of fulfillment. (as an Array of Exceptions) or <tt>nil</tt> in the
case it does fulfill it.
</p>
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>