04_subjunctive.rdoc in ae-1.1.0

- old
+ new
@@ -1,127 +1,100 @@
 = Subjunctives
 
-Okay. I can hear the BDDers rumbling, "where's the 'should'?"
-Well, AE has nothing against 'should', but there are different
+Okay. I can hear the BDDers rumbling, "where's the *should?*"
+AE has nothing against "should", but there are different
 approaches for utilizing should nomenclature in specifications,
 and AE wants to be open to these techniques. One of which
-it the way Shoulda (http://shoulda.rubyforge.org) utilizes
+is how Shoulda (http://shoulda.rubyforge.org) utilizes
 +should+ in a way analogous to RSpec's use of +it+.
 
-Even so, AE provides a an optional mixin called Subjunctive which
-can be used to create assertor methods using English subjunctive
-terms such as +should+ (or +must+, +shall+ and +will+. Whatever you like.)
+Even so, AE provides a an optional mixin called +Subjunctive+ which
+can be used to create assertor methods with English subjunctive
+terms, such as +should+, or +must+, +shall+ and +will+.
 To load this library use:
 
   require 'ae/subjunctive'
 
-Then all that is required it to define your subjunctive method for all
+Then all that is required it to define a subjunctive method for all
 objects. For example:
 
   def will(*args, &block)
     Assertor.new(self, :backtrace=>caller).be(*args,&block)
   end
 
-It's that easy. Because of their popularity AE provides two such terms,
-+should+ and +must+ as optional add-ons.
+It's that easy. Because of their commonality AE provides two such terms,
++should+ and +must+ as optional add-ons out-of-the-box.
 
   require 'ae/subjunctive/should'
   require 'ae/subjunctive/must'
 
 We will use these two methods interchangeable for the rest of this
 demonstration, but to be clear they both work exactly the same way,
-and almost exactly like #assert.
+and almost exactly like +assert+.
 
-Keep in mind, AE "conical" functionality does not entail subjunctive
-forms, or +should+ or +must+ assertor methods. These are simply options
-you can load via your test_helper.rb, or similar script, if you prefer
-or need to support these nomenclatures.
+Keep in mind, AE "conical" functionality does not entail the subjunctive
+forms. These are simply options you can load via your <tt>test_helper.rb</tt>,
+or similar script, if you prefer these nomenclatures.
 
 
 == Fluent Notation and Antonyms
 
-Like +assert+, +should+ and +must+ can be used as a higher order function.
+Like +assert+, +should+ and +must+ can be used as higher order functions.
 
   4.should == 4
   4.must   == 4
 
-With the antonym of +should!+ (read as "should not") or +shouldnt+, and for
-+must+, +must!+ or +wont+.
+Antonyms provided for +should+ as <tt>should!</tt> (read "should not") and +shouldnt+.
+For +must+ +must+, they are <tt>must!</tt> and +wont+.
 
   4.should!  == 5
   4.shouldnt == 5
 
   4.must! == 5
   4.wont  == 5
 
 
 == To Be
 
-On occasions where the English readability of a specification is
-hindered, +be+ can be used.
+On occasions where the English readability of a specification is hindered,
++be+ can be used.
 
   StandardError.must.be.raised? do
     unknown_method
   end
 
 The +be+ method is the same as +assert+ with the single exception
 that it will compare a lone argument to the receiver using +equate?+,
-unlike +assert+ which simply check to see that the argument evalutates
+unlike +assert+ which simply checks to see that the argument evaluates
 as true.
 
   10.should.be 10
   10.should.be 10.0
   10.should.be Numeric
 
+  Assertion.assert.raised? do
+    10.should.be "40"
+  end
 
+
 == Indefinite Articles
 
-Addtional anglogic forms are 'a' and 'an', equivalent to 'be' except
-that they use +case?+ instead of +equate?+,
+Additional English forms are +a+ and +an+, equivalent to +be+ except
+that they use <tt>case?</tt> (same as <tt>#===</tt>) instead of
+<tt>equate?</tt> when acting on a single argument.
 
   "hi".must.be.a String
 
-Otherwise they are interchangeble.
+  Assertion.assert.raised? do
+    /x/.must.be.a /x/
+  end
 
+Otherwise they are interchangeable.
+
   "hi".must.be.an.instance_of?(String)
 
-The indefinite articles work well when a noun follow as an arguments.
+The indefinite articles work well when a noun follows as an arguments.
 
-
   palindrome = lambda{ |x| x == x.reverse }
 
   "abracarba".must.be.a palindrome
-
-
-== Verifying Object State
-
-The block notation of the subjunctive form is similar to +assert+, with 
-the important exception that the block is is evaluated in the scope of the
-receiver via #instance_eval, if no block parameter is designated.
-This can be also be used to test 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 seem controversial --to test underlying
-implementation. And you will get no argument here, it should be used
-thoughtfully, but there are occasions when such validations are
-necessary.
-
-QED.
 