ae 1.0.0 → 1.1.0

data/MANIFEST

@@ -4,6 +4,7 @@ demo/01_overview.rdoc
 demo/02_assertion.rdoc
 demo/03_assert.rdoc
 demo/04_subjunctive.rdoc
+demo/05_expect.qed
 doc/qedoc
 doc/qedoc/index.html
 doc/qedoc/jquery.js
@@ -13,6 +14,7 @@ lib/ae/assert.rb
 lib/ae/assertion.rb
 lib/ae/assertor.rb
 lib/ae/core_ext.rb
+lib/ae/expect.rb
 lib/ae/subjunctive
 lib/ae/subjunctive/must.rb
 lib/ae/subjunctive/should.rb
@@ -35,5 +37,5 @@ meta/title
 meta/version
 test
 LICENSE
-README
+README.rdoc
 HISTORY

data/{README → README.rdoc}

@@ -1,11 +1,11 @@
 = A.E. -- Assertive Expressive
 
-* http://protuils.rubyforge.org/ae
+* http://proutils.rubyforge.org/ae/
 
 
 == DESCRIPTION
 
-Assertions Expressive (A.E.) is an assertions framework
+Assertive Expressive (A.E.) is an assertions framework
 intended for reuse by any TDD, BDD or similar system.
 
 
@@ -14,7 +14,7 @@ intended for reuse by any TDD, BDD or similar system.
 * Clear, simple and concise syntax.
 * Uses higher-order functions and fluid notation.
 * Reusable core extensions ease assertion construction.
-* Core extensions are stable and standardized via Ruby Facets.
+* Core extensions are standardized around Ruby Facets.
 * Facets is an optional dependency; extensions are built-in.
 * Easily extensible allowing for alternate notations.
 * Eats it's own dog food.
@@ -38,12 +38,11 @@ the result of which is likewise verified.
 
   assert{true}
 
-But these are simply legacy compatibility modes. The true power the
-AE's +assert+ method, lies in it's use without argument or block.
-In this case, it returns an +Assertor+ instance. An +Assertor+ is an
-Assertion Functor, or Higher-Order Function, which is a function
-that operates on another function. With it we can make assertions
-like:
+However, the true power the AE's +assert+ method, lies in it's use
+without argument or block. In this case, it returns an instance of
++Assertor+. An +Assertor+ is an <i>Assertions Functor</i> --also 
+called a Higher-Order Function, it is a function that operates on
+another function. With it, we can make assertions like:
 
   x.assert == y
 
@@ -53,22 +52,46 @@ like:
     ...
   end
 
-And so forth. AE's abilities in this areas are quite extensive.
-You are encouraged to read the QEDocs to learn more.
+And so forth. Any method can be used in conjunction with +assert+
+to make an assertion. Eg.
+
+  class String
+    def daffy?
+      /daffy/i =~ self
+    end
+  end
+
+  "Daffy Duck".assert.daffy?
+
+Please have a look at the QEDocs and RDocs to learn more.
 
 
 == HOW TO INSTALL
 
-To install with RubyGems simply open a console and type:
+=== Gem Installs
+
+AE releases it's gems via Gemcutter. If you don't have Gemcutter
+installed do:
+
+  $ gem install gemcutter
+  $ gem tumble
+
+Then you can install AE with:
 
   gem install ae
 
-Local installation requires Setup.rb (gem install setup),
-then download the tarball package and type:
+=== Site Installs
+
+Local installation requires Setup.rb.
+
+  gem install setup
+
+Then download the tarball package from GitHub (under pack/ directory)
+and do:
 
-  tar -xvzf ae-1.0.0.tgz
-  cd ae-1.0.0.tgz
-  sudo setup.rb all
+  $ tar -xvzf ae-1.0.0.tgz
+  $ cd ae-1.0.0.tgz
+  $ sudo setup.rb all
 
 Windows users use 'ruby setup.rb all'.
 

data/demo/01_overview.rdoc

@@ -14,19 +14,16 @@ Requiring the AE library.
   require 'ae'
 
 Loads two classes, +Assertion+ and +Assertor+, the Kernel
-method +assert+ and it's ancillaries +assert!+ and +refute+
+method +assert+ and it's ancillaries <tt>assert!</tt> and +refute+
 and a set of core extensions that make writing certain types
 of assertions easier.
 
 
 == Assertion and Assertor Classes
 
-The +Assertion+ class is a subclass of +Exception+. It is the
-error raised when an assertion fails. 
-
 The +Assertion+ class is at the heart of AE. All other AE
-method resolve by... The +Assertion+ class is at subclass
-of Exception. When an assertion is made, and fails, it is
+methods depend on it. The +Assertion+ class is a subclass
+of Exception. When an assertion is made and fails, it is
 an instance of Assertion that is raised.
 
   Assertion.assert.raised? do
@@ -35,33 +32,31 @@ an instance of Assertion that is raised.
   end
 
 Like any raised exception, the last Assertion message is available
-via +$!+.
+via <tt>$!</tt>.
 
-(FYI, in Test::Unit the equivalent class was called AssertionFailureError.
-AE has adopted the shortened term for my fingers sake ;) Also, recently
-it was discoverd to be the choosen term in minitest --proving good ideas
-find their way to the top.)
+(FYI, in Test::Unit the equivalent class was called +AssertionFailedError+.)
 
-Assertions themsevles are not generally used in creating tests or
-behavior specifications. Rather they are used to create additonal
+Assertions themselves are not generally used in creating tests or
+behavior specifications. Rather they are used to create additional
 types of assertion methods.
 
-As mentioned above the +Assertor+ class is a type of Functor,
-or Higher-Order function, which intercedes with a normal message
+As mentioned above the +Assertor+ class is a type of Higher-Order
+function, or Functor, which intercedes with a normal message
 invocation to monitor for failed conditions, upon which is raises
 Assertion exceptions.
 
 
 == Assertion Methods
 
-The three methods, +assert+, +assert!+ and +refute+ all return
-an Assertor instance when used fluidly, i.e. magic-dot notation,
-higher-order notation, functor notation, whatever you prefer
-to call it.
+The three methods, +assert+, <tt>assert!</tt> and +refute+ all
+return an Assertor instance when used fluidly, i.e. magic-dot
+notation, higher-order notation, functor notation, whatever you
+prefer to call it.
 
   assert(Assertor === assert)
 
-This allows us to write statements like:
+Through the use of +method_missing+, the Assertor allows us to write
+statements like:
 
   1.assert == 1
 
@@ -72,20 +67,20 @@ is raised.
     1.assert == 2
   end
 
-The methods +assert!+ and +refute+ are just like +assert+ expect
-they purport the negative condition. Patterned after Ruby's own
-use of +!+ as meaning +not+, +assert!+ should be read "assert not".
-While +refute+ exists for the sake of those that find the use of
-a "bang method" for this purpose unsuited to them.
+The methods <tt>assert!</tt> and +refute+ are just like +assert+
+expect they purport the negative condition. Patterned after Ruby's
+own use of "<tt>!</tt>" as meaning +not+, <tt>assert!</tt> should be
+read "assert not". While +refute+ exists for the sake of those who
+find the use of a bang method for this purpose unsuited to them.
 
 
-== How It All Works
+== How It Works
 
 An Assertor essentially sits in wait for a method call (via
-method_missing). When that happens it applies the method to
-the original receiver, but wrapped in a clause that raises
-an Assertion should the statement fail. If we wanted to
-be pedantic, we could write our assertions like:
+method_missing). When that happens it applies the method to the
+original receiver, but wrapped in a clause that raises an
+Assertion should the statement fail. If we wanted to be 
+pedantic, we could write our assertions like:
 
   raise Assertion.new("1 != 1") unless 1 == 1
 

data/demo/03_assert.rdoc

@@ -2,10 +2,10 @@
 
 == 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.
 
@@ -18,7 +18,7 @@ the assertion fail.
 
 == 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
@@ -42,18 +42,18 @@ into the block as a block argument.
 
 == 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
 
@@ -65,11 +65,11 @@ 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)
@@ -77,10 +77,10 @@ to make it a bit more clear.
 
 == 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
 
@@ -88,7 +88,7 @@ identity. In addition there is *Type Equality*.
     17.assert.eql? 17.0
   end
 
-And there is *Case Equality*.
+And there is <i>case equality</i>.
 
   Numeric.assert === 3
 
@@ -98,10 +98,10 @@ And there is *Case Equality*.
 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
@@ -115,7 +115,7 @@ And should it fail...
     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
@@ -142,7 +142,7 @@ in the document to verify assertion failures.
 
 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
@@ -158,14 +158,14 @@ necessay. Assert combined with +instance_eval+ makes it easy too.
 
 == 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 }
   
@@ -191,7 +191,7 @@ 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?
@@ -226,5 +226,38 @@ create reusable assertions.
 
   "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.
 

data/demo/04_subjunctive.rdoc

@@ -1,51 +1,50 @@
 = 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
@@ -56,8 +55,8 @@ With the antonym of +should!+ (read as "should not") or +shouldnt+, and for
 
 == 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
@@ -65,63 +64,37 @@ hindered, +be+ can be used.
 
 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
 
-  "hi".must.be.an.instance_of?(String)
+Otherwise they are interchangeable.
 
-The indefinite articles work well when a noun follow as an arguments.
+  "hi".must.be.an.instance_of?(String)
 
+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.
-