03_assert.rdoc in ae-1.1.0

- old
+ new

@@ -1,13 +1,13 @@
 = Assert Method
 
 == Compatible with Test::Unit
 
-The +#assert+ method is designed to be backward compatible
-with the same method in +Test::Unit+.
+The +assert+ method is designed to be backward compatible
+with the same method in <tt>Test::Unit</tt>.
 
-Using an argument, #assert will check that an argument evaluates
+Using an argument, +assert+ will check that an argument evaluates
 to true. Optionally one can send along a meaningful message should
 the assertion fail.
 
   assert(true, "Not true!")
 
@@ -16,11 +16,11 @@
   end
 
 
 == Assert with a Block
 
-In addition #assert has been extended to accept a block. Like the case of the
+In addition +assert+ has been extended to accept a block. Like the case of the
 argument, the block is expected to return something that evaluates as true.
 
   assert do
     true
   end
@@ -40,22 +40,22 @@
   end
 
 
 == Antonyms for Assert
 
-We can state the opposite assertion using #assert!
+We can state the opposite assertion using <tt>assert!</tt>.
 
   10.assert! == 9
 
-Or, because some people do not like the use of a bang method, +#refute+.
+Or, because some people do not like the use of a bang method, +refute+.
 
   10.refute == 9
 
-These terms can be used just as #assert is used in all examples,
+These terms can be used just as +assert+ is used in all examples,
 but with the opposite inference.
 
-Another way to get the opposite inference, is to use #not.
+Another way to get the opposite inference, is to use +not+.
 
   10.assert.not == 9
 
 
 == Identity Assertions
@@ -63,47 +63,47 @@
 Rather then the general form:
 
   x = 10
   x.assert.object_id == x.object_id
 
-We can use Ruby's own +equal?+ method.
+We can use Ruby's own <tt>equal?</tt> method.
 
   x.assert.equal?(x)
 
-AE provides +identical?+ method as an alternative
+AE provides <tt>identical?</tt> method as an alternative
 to make it a bit more clear.
 
   x.assert.identical?(x)
 
 
 == Equality Assertions
 
-The most common assertion is that of value equality (+==_),
+The most common assertion is that of value equality (<tt>==</tt>),
 as we have seen throughout this document. But other forms of
 equality can be verified as easily. We have already mentioned 
-identity. In addition there is *Type Equality*.
+identity. In addition there is <i>type equality</i>.
 
   17.assert.eql? 17
 
   Assertion.assert.raised? do
     17.assert.eql? 17.0
   end
 
-And there is *Case Equality*.
+And there is <i>case equality</i>.
 
   Numeric.assert === 3
 
 
 == Checking Equality with a Block
 
 Because operators can not take blocks, and at times blocks can
 be convenient means of supplying a value to an assertion,
 AE has defined alternate renditions of the equality methods.
-For equal? and eql?, the method name remains the same, they simply
-can take a block instead of argument if need be.
+For equal? and eql?, the method names are the same, they simply
+can take a block in place of an argument if need be.
 
-For *Value Equality*, +==+, the method is called +eq?+.
+For <i>value equality</i> (<tt>==</tt>), the method is called <tt>eq?</tt>.
 
   10.assert.eq? do
     10.0
   end
 
@@ -113,11 +113,11 @@
     10.assert.eq? do
       20
     end
   end
 
-For *Case Equality, +===+, it is +case?+.
+For <i>case equality</i> (<tt>===</tt>), it is <tt>case?</tt>.
 
   Numeric.assert.case? do
     "3".to_i
   end
 
@@ -140,11 +140,11 @@
 
 == Assertions on Object State
 
 While testing or specifying the internal state of an object is
 generally considered poor form, there are times when it is 
-necessay. Assert combined with +instance_eval+ makes it easy too.
+necessary. Assert combined with +instance_eval+ makes it easy too.
 
   class X
     attr :a
     def initialize(a); @a = a; end
   end
@@ -156,18 +156,18 @@
   end
 
 
 == Catch/Try Assertions
 
-Catch/Try throws can be tested via +Symbol#thrown?+.
+Catch/Try throws can be tested via <tt>Symbol#thrown?</tt>.
 
   :hookme.assert.thrown? do
     throw :hookme
   end
 
 Alternatively, a lambda containing the potential throw
-can be the receiver using +throws?+.
+can be the receiver using <tt>throws?</tt>.
 
   hook = lambda{ throw :hookme }
   
   hook.assert.throws?(:hookme)
 
@@ -189,11 +189,11 @@
 
 Ruby already provides the #nil? method.
 
   nil.assert.nil?
 
-AE add true? and false? which acts accordingly.
+AE adds <tt>true?</tt> and <tt>false?</tt> which acts accordingly.
 
   true.assert.true?
   false.assert.false?
 
 
@@ -224,7 +224,40 @@
 
   palindrome = lambda{ |x| x == x.reverse }
 
   "abracarba".assert palindrome
 
-QED.
+
+== Verifying Object State
+
+NOTE: <i>This functionality is not currently supported, but is being
+considered for a future version.</i>
+
+If no block parameter is designated and the receiver differs from +self+
+in scope of the given block, then the block is evaluated in the scope of
+the receiver via +instance_eval+. This can be also be used to verify the
+state of an object.
+
+  class X
+    attr :a
+    def initialize(a); @a = a; end
+  end
+
+  x = X.new(4)
+
+  x.must do
+    4 == @a
+  end
+
+And should it fail...
+
+  Assertion.assert.raised? do
+    x.must do
+      5 == @a
+    end
+  end
+
+For some this might be considered poor form, i.e. to test underlying
+implementation. You will get no argument here. It should be used
+thoughtfully, but I would not bet against there being occasions
+when such validations might be handy.
 