assay 0.3.0 → 0.4.0

data/.ruby

@@ -1,44 +1,49 @@
---- 
-spec_version: 1.0.0
-replaces: []
-
-loadpath: 
-- lib
-name: assay
-repositories: {}
-
-conflicts: []
-
-engine_check: []
-
-title: Assay
-resources: 
-  code: http://github.com/rubyworks/assay
-  docs: http://rubydoc.info/gems/assay
-  home: http://rubydoc.info/gems/assay
-maintainers: []
-
-requires: 
-- group: []
-
-  name: ansi
-  version: ">=1.2.5"
-- group: 
+---
+source:
+- meta
+authors:
+- name: Thomas Sawyer
+  email: transfire@gmail.com
+copyrights:
+- holder: Thomas Sawyer
+  year: '2009'
+  license: BSD-2-Clause
+replacements: []
+alternatives: []
+requirements:
+- name: ansi
+- name: brass
+- name: detroit
+  groups:
   - build
-  name: redline
-  version: 0+
-- group: 
+  development: true
+- name: qed
+  groups:
   - test
-  name: qed
-  version: 0+
-suite: rubyworks
-manifest: MANIFEST.txt
-version: 0.2.0
-licenses: 
-- Apache 2.0
-copyright: Copyright (c) 2007 Thomas Sawyer
-authors: 
-- Thomas Sawyer
-description: The Assay project defines Assertions in the same way that Ruby defines Exceptions. An asserition then simply becomes an extension to an Exception class.
+  development: true
+dependencies: []
+conflicts: []
+repositories:
+- uri: git@github.com:rubyworks/assay.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubydoc.info/gems/assay
+  docs: http://rubydoc.info/gems/assay
+  code: http://github.com/rubyworks/assay
+  mail: http://groups.google.com/groups/rubyworks-mailinglist
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2009-08-21'
 summary: Class-based Assertions Framework
-created: 2009-08-21
+title: Assay
+version: 0.4.0
+name: assay
+description: ! 'The Assay project defines Assertions in the same way that Ruby defines
+  Exceptions.
+
+  An asserition then simply becomes an extension to an Exception class.'
+organization: Rubyworks
+date: '2012-01-25'

data/COPYING.rdoc

@@ -0,0 +1,38 @@
+= COPYRIGHT
+
+== NOTICES
+
+=== Assay
+
+Copyright:: (c) 2012 RubyWorks
+License::   (r) BSD-2-Clause
+Website::   http://rubyworks.github.com/assay
+
+== LICENSES
+
+=== BSD-2-Clause License
+
+    Assay
+
+    Copyright (c) 2012 Rubyworks. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+       1. Redistributions of source code must retain the above copyright notice,
+          this list of conditions and the following disclaimer.
+
+       2. Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+    OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/HISTORY.rdoc

@@ -1,5 +1,22 @@
 = HISTORY
 
+== 0.4.0 | 1012-01-25
+
+Version 0.4 is a very polished partial rewrite of the Assay project.
+This release sheds all ancillary code to separate projects. The 
+compatibility layers are now `assay-testunit`, `assay-minitest` and
+`assay-rspec`. The built-in grammar is now the `fluidity` project.
+All assertion classes now end with `Assay` suffix instead of `Failure`
+and they are defined at the toplevel.
+
+Changes:
+
+* Spin-off all ancillary code, leaving only core functionality.
+* Polish and semi-rewrite code.
+* Renamed all Assertion subclasses form xxxFailure to xxxAssay.
+* Add many new Assertion subclasses.
+
+
 == 0.3.0 | 2011-05-07
 
 This release fix the interface of the assertive methods so they accept
@@ -17,7 +34,7 @@ This release of Assay is in good working order and can now be used
 by other frameworks such as A.E. The only caveats at this point
 are the Matcher API, which is still a bit unstable as the names of
 some of its methods may yet change, and the error messages
-for the vairous Failure classes still need improvement.
+for the various Failure classes still need improvement.
 
 Changes:
 

data/QED.rdoc

@@ -0,0 +1,1100 @@
+Assay is an foundational assertion framework.
+
+
+# Assay Classes
+
+
+## NilAssay
+
+The `NilAssay` asserts that an object reference is `nil`.
+Reference to any other object will fail.
+
+    assert NilAssay.pass?(nil)
+
+    refute NilAssay.pass?(true)
+    refute NilAssay.pass?(false)
+    refute NilAssay.pass?("foo")
+
+And conversely,
+
+    assert NilAssay.fail?(true)
+    assert NilAssay.fail?(false)
+    assert NilAssay.fail?("foo")
+
+    refute NilAssay.fail?(nil)
+
+Making assertions,
+
+    assert NilAssay.assert!(nil)
+
+    expect ::NilAssay do
+      NilAssay.assert!(true)
+    end
+
+And refutations,
+
+    assert NilAssay.refute!(true)
+
+    expect ::NilAssay do
+      NilAssay.refute!(nil)
+    end
+
+
+## BooleanAssay
+
+The `BooleanAssay` asserts that an object reference is `nil`.
+Reference to any other object will fail.
+
+    assert BooleanAssay.pass?(true)
+    assert BooleanAssay.pass?(false)
+
+    refute BooleanAssay.pass?(nil)
+    refute BooleanAssay.pass?("foo")
+
+And conversely,
+
+    assert BooleanAssay.fail?(nil)
+    assert BooleanAssay.fail?("foo")
+
+    refute BooleanAssay.fail?(true)
+    refute BooleanAssay.fail?(false)
+
+Making assertions,
+
+    assert BooleanAssay.assert!(true)
+
+    expect ::BooleanAssay do
+      BooleanAssay.assert!(nil)
+    end
+
+And refutations,
+
+    assert BooleanAssay.refute!(nil)
+
+    expect ::BooleanAssay do
+      BooleanAssay.refute!(true)
+    end
+
+
+## FalseAssay
+
+The `FalseAssay` class asserts that an object is `false.
+Reference to any other object will fail.
+
+    assert FalseAssay.pass?(false)
+
+    refute FalseAssay.pass?(true)
+    refute FalseAssay.pass?(nil)
+    refute FalseAssay.pass?('foo')
+
+And conversely,
+
+    assert FalseAssay.fail?(true)
+    assert FalseAssay.fail?(nil)
+    assert FalseAssay.fail?('foo')
+
+    refute FalseAssay.fail?(false)
+
+
+## TrueAssay
+
+The `TrueAssay` class asserts that an object is `true`.
+Reference to any other object will fail.
+
+    assert TrueAssay.pass?(true)
+
+    refute TrueAssay.pass?(false)
+    refute TrueAssay.pass?(nil)
+    refute TrueAssay.pass?('foo')
+
+And conversely,
+
+    assert TrueAssay.fail?(false)
+    assert TrueAssay.fail?(nil)
+    assert TrueAssay.fail?('foo')
+
+    refute TrueAssay.fail?(true)
+
+
+
+## LikeAssay
+
+The `LikeAssay` is a very ... assertion. It is a comparison that
+evaluates to true for any of Ruby's many "equal" operators, `equal?`
+(same as `identical?`), `eql?`, `==`, `===` and `=~`. If any one
+of these evaluates to true, than two objects can be said to be alike.
+
+    assert LikeAssay.pass?(1, 1)
+    assert LikeAssay.pass?(1, 1.0)
+    assert LikeAssay.pass?("1", /\d/)
+
+    refute LikeAssay.pass?(1, "1")
+    refute LikeAssay.pass?("1", /\D/)
+
+And conversely,
+
+    assert LikeAssay.fail?(1, "1")
+    assert LikeAssay.fail?("1", /\D/)
+
+
+## EqualAssay
+
+The `EqualAssay` class defines an assertion for equality based on the `==` method.
+
+    assert EqualAssay.pass?(1, 1)
+    assert EqualAssay.pass?(1, 1.0)
+
+    refute EqualAssay.pass?(1, 2)
+    refute EqualAssay.pass?(1, 'foo')
+
+And conversely,
+
+    assert EqualAssay.fail?(1, 2)
+    assert EqualAssay.fail?(1, 'foo')
+
+    refute EqualAssay.fail?(1, 1)
+    refute EqualAssay.fail?(1, 1.0)
+
+
+
+## UnequalAssay
+
+The `UnequalAssay` class defines an assertion for equality based on the `!=`
+method, which in Ruby 1.8 is a redefinable method all it's own.
+
+    assert UnequalAssay.pass?(1, 2)
+    assert UnequalAssay.pass?(1, 'foo')
+
+    refute UnequalAssay.pass?(1, 1)
+    refute UnequalAssay.pass?(1, 1.0)
+
+And conversely,
+
+    assert UnequalAssay.fail?(1, 1)
+    assert UnequalAssay.fail?(1, 1.0)
+
+    refute UnequalAssay.fail?(1, 2)
+    refute UnequalAssay.fail?(1, 'foo')
+
+Making assertions,
+
+    assert UnequalAssay.assert!(10, 20)
+
+    expect ::UnequalAssay do
+      UnequalAssay.assert!(10, 10)
+    end
+
+And refutations,
+
+    assert UnequalAssay.refute!(10, 10)
+
+    expect ::UnequalAssay do
+      UnequalAssay.refute!(10, 20)
+    end
+
+
+## EqualityAssay
+
+The `EqualityAssay` class defines an assertion for strict equality via
+the `eql?` method.
+
+    assert EqualityAssay.pass?(1, 1)
+
+    refute EqualityAssay.pass?(1, 1.0)
+    refute EqualityAssay.pass?(1, 2)
+    refute EqualityAssay.pass?(1, 'foo')
+
+And conversely,
+
+    assert EqualityAssay.fail?(1, 2)
+    assert EqualityAssay.fail?(1, 1.0)
+    assert EqualityAssay.fail?(1, 'foo')
+
+    refute EqualityAssay.fail?(1, 1)
+
+
+## IdentityAssay
+
+The `IdentityAssay` class defines an assertion for identity comparison via
+the `#identical?` method, which is an alias for the `#equal?` method.
+We have choosen not to use the term `equal` to avoid confusion with the
+ordinary `==` type of equality.
+
+    assert IdentityAssay.pass?(1, 1)
+    assert IdentityAssay.pass?(:a, :a)
+
+    refute IdentityAssay.pass?('a', 'a')
+    refute IdentityAssay.pass?(1, 1.0)
+    refute IdentityAssay.pass?(1, 2)
+    refute IdentityAssay.pass?(1, 'foo')
+
+And conversely,
+
+    assert IdentityAssay.fail?(1, 2)
+    assert IdentityAssay.fail?(1, 1.0)
+    assert IdentityAssay.fail?(1, 'foo')
+    assert IdentityAssay.fail?('a', 'a')
+
+    refute IdentityAssay.fail?(1, 1)
+    refute IdentityAssay.fail?(:a, :a)
+
+## CaseAssay
+
+The `CaseAssay` class defines an assertion for case equality using the `#===`
+method.
+
+    assert CaseAssay.pass?(1, 1)
+    assert CaseAssay.pass?(1, 1.0)
+    assert CaseAssay.pass?(/a/, 'a')
+    assert CaseAssay.pass?(String, 'foo')
+
+    refute CaseAssay.pass?(1, 2)
+    refute CaseAssay.pass?(1, 'foo')
+
+And conversely,
+
+    assert CaseAssay.fail?(1, 2)
+    assert CaseAssay.fail?(1, 'foo')
+
+    refute CaseAssay.fail?(1, 1)
+    refute CaseAssay.fail?(1, 1.0)
+    refute CaseAssay.fail?(/a/, 'a')
+    refute CaseAssay.fail?(String, 'foo')
+
+## MatchAssay
+
+The `MatchAssay` class defines an assertion for matching using the `#=~`
+method.
+
+    assert MatchAssay.pass?('a', /a/)
+
+    refute MatchAssay.pass?('a', /b/)
+
+And conversely,
+
+    assert MatchAssay.fail?('a', /b/)
+
+    refute MatchAssay.fail?('a', /a/)
+
+
+## NoMatchAssay
+
+The `NoMatchAssay` class defines an assertion for matching using the `#!~`
+method. As of Ruby 1.9, the `#!~` method is redefinable independent of `#=~`,
+so a separate assertion class is needed to cover it.
+
+    assert NoMatchAssay.pass?('a', /b/)
+
+    refute NoMatchAssay.pass?('a', /a/)
+
+And conversely,
+
+    assert NoMatchAssay.fail?('a', /a/)
+
+    refute NoMatchAssay.fail?('a', /b/)
+
+
+## CompareAssay
+
+The `CompareAssay` class defines an assertion of comparison around the `#<=>`
+method. Since `#<=>` can return either a `1`, `0` or `-1`, an extra criterion
+is needed when making testing the assertion.
+
+    assert CompareAssay.pass?(1, 1,  0)
+    assert CompareAssay.pass?(1, 2, -1)
+    assert CompareAssay.pass?(2, 1,  1)
+
+    refute CompareAssay.pass?(1, 1,  1)
+    refute CompareAssay.pass?(1, 1, -1)
+
+    refute CompareAssay.pass?(1, 'foo', 0)
+
+And conversely,
+
+    assert CompareAssay.fail?(1, 1,  1)
+    assert CompareAssay.fail?(1, 1, -1)
+
+    refute CompareAssay.fail?(1, 1,  0)
+    refute CompareAssay.fail?(1, 2, -1)
+    refute CompareAssay.fail?(2, 1,  1)
+
+
+## LessAssay
+
+The `LessAssay` class defines an assertion of comparison around the `#<`
+method. This method usually depends on the `#<=>` method via Ruby's Comparable
+mixin, so `LessAssay` is a subclass of `ComapreAssay`, though techincally
+the `#<` method can be defined independently.
+
+    assert LessAssay.pass?( 1, 2)
+    assert LessAssay.pass?(-1, 0)
+
+    refute LessAssay.pass?(1, 1)
+    refute LessAssay.pass?(1, 0)
+
+And conversely,
+
+    assert LessAssay.fail?(1, 1)
+    assert LessAssay.fail?(1, 0)
+
+    refute LessAssay.fail?( 1, 2)
+    refute LessAssay.fail?(-1, 0)
+
+This applies to any type of object that defines `#<=`, not just numbers.
+
+    assert LessAssay.pass?('a', 'b')
+    refute LessAssay.pass?('b', 'a')
+
+    assert LessAssay.fail?('b', 'a')
+    refute LessAssay.fail?('a', 'b')
+
+
+## MoreAssay
+
+The `MoreAssay` class defines an assertion of comparison around the `#>`
+method. This method usually depends on the `#<=>` method via Ruby's Comparable
+mixin, so `MoreAssay` is a subclass of `ComapreAssay`, though techincally
+the `#>` method can be defined indenpendently.
+
+    assert MoreAssay.pass?(2,  1)
+    assert MoreAssay.pass?(0, -1)
+    assert MoreAssay.pass?(1,  0)
+
+    refute MoreAssay.pass?(1, 1)
+    refute MoreAssay.pass?(1, 2)
+
+And conversely,
+
+    assert MoreAssay.fail?(1, 1)
+    assert MoreAssay.fail?(0, 1)
+
+    refute MoreAssay.fail?(2,  1)
+    refute MoreAssay.fail?(0, -1)
+
+This applies to any type of object that defines `#>`, not just numbers.
+
+    assert MoreAssay.pass?('b', 'a')
+    refute MoreAssay.pass?('a', 'b')
+
+    assert MoreAssay.fail?('a', 'b')
+    refute MoreAssay.fail?('b', 'a')
+
+## LessEqualAssay
+
+The `LessEqualAssay` class defines an assertion of comparison around the `#<=`
+method. This method usually depends on the `#<=>` method via Ruby's Comparable
+mixin, so `LessEqualAssay` is a subclass of `ComapreAssay`, though techincally
+the `#<=` method can be defined indenpendently.
+
+    assert LessEqualAssay.pass?( 1, 2)
+    assert LessEqualAssay.pass?(-1, 0)
+    assert LessEqualAssay.pass?( 1, 1)
+
+    refute LessEqualAssay.pass?(1, 0)
+
+And conversely,
+
+    assert LessEqualAssay.fail?(1, 0)
+
+    refute LessEqualAssay.fail?( 1, 1)
+    refute LessEqualAssay.fail?( 1, 2)
+    refute LessEqualAssay.fail?(-1, 0)
+
+This applies to any type of object that defines `#<=`, not just numbers.
+
+    assert LessEqualAssay.pass?('a', 'b')
+    refute LessEqualAssay.pass?('b', 'a')
+
+    assert LessEqualAssay.fail?('b', 'a')
+    refute LessEqualAssay.fail?('a', 'b')
+
+
+
+## MoreEqualAssay
+
+The `MoreEqualAssay` class defines an assertion of comparison around the `#>=`
+method. This method usually depends on the `#<=>` method via Ruby's Comparable
+mixin, so `MoreEqualAssay` is a subclass of `ComapreAssay`, though techincally
+the `#>=` method can be defined indenpendently.
+
+    assert MoreEqualAssay.pass?(2,  1)
+    assert MoreEqualAssay.pass?(0, -1)
+    assert MoreEqualAssay.pass?(1,  1)
+
+    refute MoreEqualAssay.pass?(0, 1)
+
+And conversely,
+
+    assert MoreEqualAssay.fail?(0, 1)
+
+    refute MoreEqualAssay.fail?( 1, 1)
+    refute MoreEqualAssay.fail?( 2, 1)
+    refute MoreEqualAssay.fail?( 0, -1)
+
+This applies to any type of object that defines `#<=`, not just numbers.
+
+    assert MoreEqualAssay.pass?('b', 'a')
+    refute MoreEqualAssay.pass?('a', 'b')
+
+    assert MoreEqualAssay.fail?('a', 'b')
+    refute MoreEqualAssay.fail?('b', 'a')
+
+
+## WithinAssay
+
+The `WithinAssay` class defines an assertion for matching that two values
+lie with a range.
+
+    assert WithinAssay.pass?(1, 1,   0)
+    assert WithinAssay.pass?(1, 1.1, 0.1)
+
+    refute WithinAssay.pass?(1, 2,   0)
+    refute WithinAssay.pass?(1, 1.2, 0.1)
+
+And conversely,
+
+    assert WithinAssay.fail?(1, 2,   0)
+    assert WithinAssay.fail?(1, 1.2, 0.1)
+
+    refute WithinAssay.fail?(1, 1,   0)
+    refute WithinAssay.fail?(1, 1.1, 0.1)
+
+The object do not have to be numbers necessaity, just so long as they
+are comparable and subtractable.
+
+    time = Time.now
+
+    assert WithinAssay.pass?(time, time+1, 2)
+
+Making assertions,
+
+    assert WithinAssay.assert!(10, 11, 1)
+
+    expect ::WithinAssay do
+      WithinAssay.assert!(10, 15, 2)
+    end
+
+And refutations,
+
+    assert WithinAssay.refute!(10, 11, 0.1)
+
+    expect ::WithinAssay do
+      WithinAssay.refute!(10, 11, 1)
+    end
+
+
+## KindAssay
+
+The `KindAssay` asserts that an object is a class or any ancestor
+of that class.
+
+    assert KindAssay.pass?(1, Fixnum)
+    assert KindAssay.pass?(1, Numeric)
+
+    refute KindAssay.pass?(1, String)
+
+And conversely,
+
+    assert KindAssay.fail?(1, String)
+
+    refute KindAssay.fail?(1, Fixnum)
+    refute KindAssay.fail?(1, Numeric)
+
+
+## InstanceAssay
+
+The `InstanceAssay` asserts that an object is an instance of a specific class.
+
+    assert InstanceAssay.pass?(1, Fixnum)
+
+    refute InstanceAssay.pass?(1, Numeric)
+    refute InstanceAssay.pass?(1, String)
+
+And conversely,
+
+    assert InstanceAssay.fail?(1, String)
+    assert InstanceAssay.fail?(1, Numeric)
+
+    refute InstanceAssay.fail?(1, Fixnum)
+
+
+## IncludeAssay
+
+The `IncludeAssay` asserts that a collection includes a specific member, using
+the `#include?` method.
+
+    assert IncludeAssay.pass?([1], 1)
+
+    refute IncludeAssay.pass?([],  1)
+    refute IncludeAssay.pass?([2], 1)
+
+And conversely,
+
+    assert IncludeAssay.fail?([],  1)
+    assert IncludeAssay.fail?([2], 1)
+
+    refute IncludeAssay.fail?([1], 1)
+
+
+## EmptyAssay
+
+The `EmptyAssay` asserts that a collection includes no members, using the 
+`#empty?` method.
+
+    assert EmptyAssay.pass?([])
+
+    refute EmptyAssay.pass?([1])
+
+And conversely,
+
+    assert EmptyAssay.fail?([1])
+
+    refute EmptyAssay.fail?([])
+
+
+## RespondAssay
+
+The `RespondAssay` asserts if a an object responds to a message using
+then `#respond_to?` method.
+
+    assert RespondAssay.pass?('a', :to_s)
+
+    refute RespondAssay.pass?('a', :foo)
+
+And conversely,
+
+    assert RespondAssay.fail?('a', :foo)
+
+    refute RespondAssay.fail?('a', :to_s)
+
+
+## ExecutionAssay
+
+The `ExecutionAssay` asserts that a procedure runs without error and returns
+a result other than `false` or `nil`. It is not particularly useful, because
+what it does is effectively what testing in itself does. So it is rather
+redundant. However, it serves as the base class for the more specific
+`ReturnAssay`.
+
+    assert ExecutionAssay.pass?{ true }
+    assert ExecutionAssay.pass?{ :foo }
+
+    refute ExecutionAssay.pass?{ nil }
+    refute ExecutionAssay.pass?{ false }
+    refute ExecutionAssay.pass?{ raise }
+
+And conversely,
+
+    assert ExecutionAssay.fail?{ raise }
+    assert ExecutionAssay.fail?{ nil }
+    assert ExecutionAssay.fail?{ false }
+
+    refute ExecutionAssay.fail?{ true }
+    refute ExecutionAssay.fail?{ :foo }
+
+Making assertions,
+
+    assert ExecutionAssay.assert!{ true }
+
+    expect ::ExecutionAssay do
+      assert ExecutionAssay.assert!{ false }
+    end
+
+And refutations,
+
+    assert ExecutionAssay.refute!{ false }
+
+    expect ::ExecutionAssay do
+      assert ExecutionAssay.refute!{ true }
+    end
+
+
+## ReturnAssay
+
+The `ReturnAssay` asserts that a procedure runs without error and returns
+a specified result.
+
+    assert ReturnAssay.pass?(:foo){ :foo }
+    assert ReturnAssay.pass?(true){ true }
+
+    refute ReturnAssay.pass?(:foo){ :bar }
+    refute ReturnAssay.pass?(:foo){ true }
+    refute ReturnAssay.pass?(:foo){ raise }
+
+And conversely,
+
+    assert ReturnAssay.fail?(:foo){ :bar }
+    assert ReturnAssay.fail?(:foo){ true }
+    assert ReturnAssay.fail?(:foo){ raise }
+
+    refute ReturnAssay.fail?(:foo){ :foo }
+    refute ReturnAssay.fail?(true){ true }
+
+Making assertions,
+
+    assert ReturnAssay.assert!(true){ true }
+
+    expect ::ReturnAssay do
+      assert ReturnAssay.assert!(:foo){ :bar }
+    end
+
+And refutations,
+
+    assert ReturnAssay.refute!(:foo){ :bar }
+
+    expect ::ReturnAssay do
+      assert ReturnAssay.refute!(:foo){ :foo }
+    end
+
+
+## RescueAssay
+
+The `RescueAssay` asserts that a procedure will raise a specific error.
+
+    assert RescueAssay.pass?{ raise }
+    assert RescueAssay.pass?(RuntimeError){ raise }
+    assert RescueAssay.pass?(ArgumentError){ raise ArgumentError }
+    assert RescueAssay.pass?(Exception){ raise ArgumentError }
+
+    refute RescueAssay.pass?{ raise Exception }
+    refute RescueAssay.pass?(RuntimeError){ nil }
+    refute RescueAssay.pass?(ArgumentError){ raise }
+
+And conversely,
+
+    assert RescueAssay.fail?{ raise Exception }
+    assert RescueAssay.fail?(RuntimeError){ nil }
+    assert RescueAssay.fail?(ArgumentError){ raise }
+
+    refute RescueAssay.fail?{ raise }
+    refute RescueAssay.fail?(RuntimeError){ raise }
+    refute RescueAssay.fail?(ArgumentError){ raise ArgumentError }
+    refute RescueAssay.fail?(Exception){ raise ArgumentError }
+
+Making assertions,
+
+    assert RescueAssay.assert!(RuntimeError){ raise }
+
+    expect ::RescueAssay do
+      RaiseAssay.assert!(RuntimeError){ nil }
+    end
+
+And refutations,
+
+    assert RescueAssay.refute!(RuntimeError){ nil }
+
+    expect ::RescueAssay do
+      RaiseAssay.refute!(RuntimeError){ raise }
+    end
+
+
+## RaiseAssay
+
+The `RaiseAssay` asserts that a procedure will raise a specific error.
+
+    assert RaiseAssay.pass?{ raise }
+    assert RaiseAssay.pass?(RuntimeError){ raise }
+    assert RaiseAssay.pass?(ArgumentError){ raise ArgumentError }
+
+    refute RaiseAssay.pass?{ raise Exception }
+    refute RaiseAssay.pass?(Exception){ raise ArgumentError }
+    refute RaiseAssay.pass?(StandardError){ nil }
+    refute RaiseAssay.pass?(ArgumentError){ raise }
+
+And conversely,
+
+    assert RaiseAssay.fail?{ raise Exception }
+    assert RaiseAssay.fail?(RuntimeError){ nil }
+    assert RaiseAssay.fail?(ArgumentError){ raise }
+    assert RaiseAssay.fail?(Exception){ raise ArgumentError }
+
+    refute RaiseAssay.fail?{ raise }
+    refute RaiseAssay.fail?(RuntimeError){ raise }
+    refute RaiseAssay.fail?(ArgumentError){ raise ArgumentError }
+
+Making assertions,
+
+    assert RaiseAssay.assert!(RuntimeError){ raise }
+
+    expect ::RaiseAssay do
+      RaiseAssay.assert!(RuntimeError){ nil }
+    end
+
+And refutations,
+
+    assert RaiseAssay.refute!(RuntimeError){ nil }
+
+    expect ::RaiseAssay do
+      RaiseAssay.refute!(RuntimeError){ raise }
+    end
+
+
+## ThrowAssay
+
+The `ThrowAssay` asserts that a procedure will call `throw` and optionally
+of a specific type.
+
+    assert ThrowAssay.pass?(:foo){ throw :foo }
+    refute ThrowAssay.pass?(:foo){ throw :bar }
+
+And conversely,
+
+    assert ThrowAssay.fail?(:foo){ throw :bar }
+    refute ThrowAssay.fail?(:foo){ throw :foo }
+
+In addition `ThrowAssay` can assert that there is a throw, regardless
+of tag.
+
+    assert ThrowAssay.pass?{ throw :foo }
+    refute ThrowAssay.pass?{ nil }
+
+And converselry,
+
+    assert ThrowAssay.fail?{ nil }
+    refute ThrowAssay.fail?{ throw :bar }
+
+Making assertions, notice that the `#assert!` method requires a `nil`
+argument in order to test for any throw. This is not needed on the 
+`#pass?` method because the `#pass` method can't take aditional options
+for setting the message or backtrace.
+
+    assert ThrowAssay.assert!(nil){ throw :foo }
+
+    assert ThrowAssay.assert!(nil, :message=>"optional message"){
+      throw :foo
+    }
+
+    expect ThrowAssay do
+      ThrowAssay.assert!(nil){ 'nothing' }
+    end
+
+And refutations,
+
+    assert ThrowAssay.refute!(:foo){ throw :bar }
+
+    expect ThrowAssay do
+      ThrowAssay.refute!(:foo){ throw :foo }
+    end
+
+
+## PathAssay
+
+The `PathAssay` asserts that a file-system path exists.
+
+    file = __FILE__
+    dir  = File.dirname(file)
+    dne  = __FILE__ + '~'
+
+    assert PathAssay.pass?(file)
+    assert PathAssay.pass?(dir)
+
+    refute PathAssay.pass?(dne)
+
+And conversely,
+
+    assert PathAssay.fail?(dne)
+
+    refute PathAssay.fail?(file)
+    refute PathAssay.fail?(dir)
+
+
+## DirectoryAssay
+
+The `DirectoryAssay` asserts that a file-system path exists
+and it is a directory.
+
+    file = __FILE__
+    dir  = File.dirname(file)
+    dne  = __FILE__ + '~'
+
+    assert DirectoryAssay.pass?(dir)
+
+    refute DirectoryAssay.pass?(file)
+    refute DirectoryAssay.pass?(dne)
+
+And conversely,
+
+    assert DirectoryAssay.fail?(file)
+    assert DirectoryAssay.fail?(dne)
+
+    refute DirectoryAssay.fail?(dir)
+
+
+## FileAssay
+
+The `FileAssay` asserts that a file-system path exists and it is a file.
+
+    file = __FILE__
+    dir  = File.dirname(file)
+    dne  = __FILE__ + '~'
+
+    assert FileAssay.pass?(file)
+
+    refute FileAssay.pass?(dir)
+    refute FileAssay.pass?(dne)
+
+And conversely,
+
+    assert FileAssay.fail?(dir)
+    assert FileAssay.fail?(dne)
+
+    refute FileAssay.fail?(file)
+
+
+## OutputAssay
+
+The `OutputAssay` asserts that a output is sent to either `$stdout` or `$stderr`.
+
+Let's do the simple stdout case first.
+
+    assert OutputAssay.pass?('foo'){ puts 'foo' }
+
+    refute OutputAssay.pass?('foo'){ nil }
+    refute OutputAssay.pass?('foo'){ puts 'bar' }
+
+And conversely,
+
+    refute OutputAssay.fail?('foo'){ puts 'foo' }
+
+    assert OutputAssay.fail?('foo'){ nil }
+    assert OutputAssay.fail?('foo'){ puts 'bar' }
+
+Now the same for `$stderr`.
+
+    assert OutputAssay.pass?('foo'){ $stderr.puts 'foo' }
+
+    refute OutputAssay.pass?('foo'){ nil }
+    refute OutputAssay.pass?('foo'){ $stderr.puts 'bar' }
+
+And conversely,
+
+    refute OutputAssay.fail?('foo'){ $stderr.puts 'foo' }
+
+    assert OutputAssay.fail?('foo'){ nil }
+    assert OutputAssay.fail?('foo'){ $stderr.puts 'bar' }
+
+The OutputAssay uses `#===` to test the match so we can also 
+match against a regular expression.
+
+    assert OutputAssay.pass?(/f/){ puts 'foo' }
+
+    assert OutputAssay.pass?(/f/){ $stderr.puts 'foo' }
+
+
+## StdoutAssay
+
+The `StdoutAssay` asserts that a output is sent to `$stdout`.
+
+    assert StdoutAssay.pass?('foo'){ puts 'foo' }
+
+    refute StdoutAssay.pass?('foo'){ nil }
+    refute StdoutAssay.pass?('foo'){ puts 'bar' }
+
+And conversely,
+
+    refute StdoutAssay.fail?('foo'){ puts 'foo' }
+
+    assert StdoutAssay.fail?('foo'){ nil }
+    assert StdoutAssay.fail?('foo'){ puts 'bar' }
+
+The StdoutAssay uses `#===` to test the match so we can also 
+match against a regular expression.
+
+    assert StdoutAssay.pass?(/f/){ puts 'foo' }
+
+
+## StderrAssay
+
+The `StderrAssay` asserts that a output is sent to `$stderr`.
+
+    assert StderrAssay.pass?('foo'){ $stderr.puts 'foo' }
+
+    refute StderrAssay.pass?('foo'){ nil }
+    refute StderrAssay.pass?('foo'){ $stderr.puts 'bar' }
+
+And conversely,
+
+    refute StderrAssay.fail?('foo'){ $stderr.puts 'foo' }
+
+    assert StderrAssay.fail?('foo'){ nil }
+    assert StderrAssay.fail?('foo'){ $stderr.puts 'bar' }
+
+The StderrAssay uses `#===` to test the match so we can also 
+match against a regular expression.
+
+    assert StderrAssay.pass?(/f/){ $stderr.puts 'foo' }
+
+
+# Asay Lookup
+
+Assay classes are indexed by both name and associated operation, so they
+can be looked-up by either. The indexes are stored as class attributes of
+the Assertion base class.
+
+Let's lookup the class for `==` equality.
+
+  Assertion.by_operator(:==)      #=> ::EqualAssay
+
+Let's lookup the assertion class for `#empty?`.
+
+  Assertion.by_operator(:empty?)  #=> ::EmptyAssay
+
+If we wish to lookup by assertive name instead of operator, we can use
+the `by_name` method instead.
+
+  Assertion.by_name(:empty)       #=> ::EmptyAssay
+
+We can also use the `Assay.lookup` module method, which will lookup an assay
+class by either assertion name or associated operator.
+
+  Assay.lookup(:==)               #=> ::EqualAssay
+  Assay.lookup(:empty?)           #=> ::EmptyAssay
+
+
+# Assay as Assertor
+
+Assay classes can be converted to assertors, otherwise known as *matchers* in
+RSpec circles. The idea behind Assertors is that they can be initialized with
+pre-set criteria and then applied to target subjects.
+
+## Standard Target Matching
+
+    assertor = EqualAssay[1]
+
+    assertor.assert!(1)
+
+    expect EqualAssay do
+      assertor.assert!(2)
+    end
+
+## Partial Arguments
+
+    assertor = LessAssay[1,__]
+
+We can apply the assertor using the `#pass!` method.
+
+    assertor.assert!(2)
+
+Likewise we can assert the negated expression using `#fail!`.
+
+    assertor.refute!(0)
+
+Assay partial a very versile because they allow any argument to become
+the target of a assertor.
+
+    assertor = CompareAssay[2,1,__]
+
+    assertor.assert!(1)
+    assertor.refute!(0)
+
+## Match Operator
+
+The `#=~` method is an alias for `#assert!`.
+
+    assertor = EqualAssay[1]
+    assertor =~ 1
+
+Conversely, `#!~` method is an alias for `#refute!`.
+
+    assertor !~ 2
+
+## Case Operator
+
+The `#===` method is also an alias for `#assert!`.
+
+    assertor === 1
+
+This allows the `case` statement to be used in an intersting way.
+
+    case 10
+    when KindAssay[Numeric]
+    when EqualAssay[10.0]
+    end
+
+## Negated Assertors
+
+Assertors can also be negated so that pass and fail methods swap behaviors.
+
+    assertor = EqualityAssay[1]
+
+    assertor.not =~ 2
+    assertor.not !~ 1
+
+For conveience we can also negate the assertor using the `~` unary operator.
+
+    !assertor === 2
+
+## Just Cheking
+
+Assertors can also be used just to test the assertion without actually 
+raising the associated exception.
+
+    assertor = EqualityAssay[__,1]
+
+    assertor.pass?(1)
+    assertor.fail?(2)
+
+## RSpec Compatability
+
+RSpec compatibality is provided via neccessary method alias, in particular
+`#matches?` and `#does_not_match?`.
+
+    assertor = EqualityAssay[__,1]
+
+    assert assertor.matches?(1)
+    assert assertor.does_not_match?(2)
+
+Error messages are handle by RSpec by `#failure_message_for_should` and
+`#failure_message_for_should_not`.
+
+    assertor.failure_message_for_should(1)
+    assertor.failure_message_for_should_not(2)
+
+
+# Assay Class Methods
+
+## Metadata
+
+Assay support full project metadata access thanks to the `.ruby`
+standard.
+
+    Assay.metadata['name']  #=> 'assay'
+
+The metadata also dynamically translates into constants, so we
+can work with this information in the traditional fashion.
+
+    Assay::NAME  #=> 'assay'
+
+## Color Messages
+
+We can have some Assay error messages use ANSI color output by
+setting the `Assay.color` setting to `true`.
+
+    Assay.color = true
+
+Keep in mind that this requires the `ansi` library.
+
+In particular it is the equality related assertions that utilize color
+output when the objects compared are large. This helps the developer
+pinpint the differences quickly.
+
+    expect EqualAssay do
+      EqualAssay['really long string'] === 'other string'
+    end
+
+## Lookup Assay Classes
+
+Assay tracks all created Assay classes by both associated operation
+and assertive name.
+
+    Assay.lookup_by_operator(:==)  #=> EqualAssay
+
+    Assay.lookup_by_name(:equal)   #=> EqualAssay
+
+We can look for either with just `lookup`.
+
+    Assay.lookup(:==)      #=> EqualAssay
+    Assay.lookup(:equal)   #=> EqualAssay
+
+
+