ae 1.0.0 → 1.1.0

data/demo/05_expect.qed

@@ -0,0 +1,83 @@
+= Expect Method
+
+Expect is another optional assertion nomenclature available
+for use in your tests or specifications. Inspired by Jay Fields'
+Expectations library, it provides convenient syntax for creating
+exception and case equality assertions.
+
+
+== Underlying Comparison
+
+Expect uses #=== for comparison. So providing an argument and a block to
+#expect we can test for a somewhat broader range of compassion than #assert.
+For example we can test for a subclass.
+
+  expect Numeric do
+    3
+  end
+
+  Assertion.assert.raised? do
+    expect Numeric do
+      "3"
+    end
+  end
+
+
+== Exception Expectation
+
+If the comparator is an Exception class or a instance of an Exception class,
+then #expect will check to see if the block raises that kind of exception.
+
+  expect StandardError do
+    some_undefined_method
+  end
+
+  expect Assertion do
+    expect(nil)
+  end
+
+This is an important distinction to note because it means #expect can not be used
+if verify instances of Exception classes.
+
+  Assertion.assert.raised? do
+    expect Exception do
+      Exception.new
+    end
+  end
+
+
+== Regex Expectations
+
+That #expect entails #=== also means we can check for Regexp matches.
+
+  expect /x/ do
+    "oooxooo"
+  end
+
+
+== Expected Method
+
+We can use #expected to make the receiver the object of expectation.
+
+  x = "dummy"
+
+  /x/.expected do
+    "x"
+  end
+
+
+== Function without Block
+
+Without a block, the receiver is compared to the argument.
+
+  x.expect String
+
+
+== Functor, or Higher Order Function
+
+Like #assert, #expect can be used used as a *fluid* notation.
+
+  10.expect == 10
+
+In which case it works just like #assert.
+

data/doc/qedoc/index.html

@@ -8,7 +8,7 @@
     /* Debug borders */
     /* p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { border: 1px solid red; } */
 
-    body { font-size: 16px; line-height: 20px; margin: 1em 5% 1em 5%; font-family: Verdana, Arial, Helvetica, sans-serif; }
+    body { font-size: 14px; line-height: 20px; margin: 1em 5% 1em 5%; font-family: Verdana, Arial, Helvetica, sans-serif; }
     a { color: #336; text-decoration: underline; }
     a:visited { color: #334; }
     em { font-style: italic; }
@@ -114,20 +114,16 @@ Requiring the AE library.
 </pre>
 <p>
 Loads two classes, <tt>Assertion</tt> and <tt>Assertor</tt>, the Kernel
-method <tt>assert</tt> and it&#8217;s ancillaries +assert!+ and
+method <tt>assert</tt> and it&#8217;s ancillaries <tt>assert!</tt> and
 <tt>refute</tt> and a set of core extensions that make writing certain
 types of assertions easier.
 </p>
 <h2>Assertion and Assertor Classes</h2>
 <p>
-The <tt>Assertion</tt> class is a subclass of <tt>Exception</tt>. It is the
-error raised when an assertion fails.
-</p>
-<p>
-The <tt>Assertion</tt> class is at the heart of AE. All other AE method
-resolve by&#8230; The <tt>Assertion</tt> class is at subclass of Exception.
-When an assertion is made, and fails, it is an instance of Assertion that
-is raised.
+The <tt>Assertion</tt> class is at the heart of AE. All other AE methods
+depend on it. The <tt>Assertion</tt> class is a subclass of Exception. When
+an assertion is made and fails, it is an instance of Assertion that is
+raised.
 </p>
 <pre>
   Assertion.assert.raised? do
@@ -137,13 +133,11 @@ is raised.
 </pre>
 <p>
 Like any raised exception, the last Assertion message is available via
-+$!+.
+<tt>$!</tt>.
 </p>
 <p>
-(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 &#8212;proving good ideas
-find their way to the top.)
+(FYI, in Test::Unit the equivalent class was called
+<tt>AssertionFailedError</tt>.)
 </p>
 <p>
 Assertions themsevles are not generally used in creating tests or behavior
@@ -151,21 +145,22 @@ specifications. Rather they are used to create additonal types of assertion
 methods.
 </p>
 <p>
-As mentioned above the <tt>Assertor</tt> class is a type of Functor, or
-Higher-Order function, which intercedes with a normal message invocation to
+As mentioned above the <tt>Assertor</tt> 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.
 </p>
 <h2>Assertion Methods</h2>
 <p>
-The three methods, <tt>assert</tt>, +assert!+ and <tt>refute</tt> all
-return an Assertor instance when used fluidly, i.e. magic-dot notation,
+The three methods, <tt>assert</tt>, <tt>assert!</tt> and <tt>refute</tt>
+all return an Assertor instance when used fluidly, i.e. magic-dot notation,
 higher-order notation, functor notation, whatever you prefer to call it.
 </p>
 <pre>
   assert(Assertor === assert)
 </pre>
 <p>
-This allows us to write statements like:
+Through the use of <tt>method_missing</tt>, the Assertor allows us to write
+statements like:
 </p>
 <pre>
   1.assert == 1
@@ -180,14 +175,14 @@ raised.
   end
 </pre>
 <p>
-The methods +assert!+ and <tt>refute</tt> are just like <tt>assert</tt>
-expect they purport the negative condition. Patterned after Ruby&#8217;s
-own use of +!+ as meaning <tt>not</tt>, +assert!+ should be read
-&quot;assert not&quot;. While <tt>refute</tt> exists for the sake of those
-that find the use of a &quot;bang method&quot; for this purpose unsuited to
-them.
+The methods <tt>assert!</tt> and <tt>refute</tt> are just like
+<tt>assert</tt> expect they purport the negative condition. Patterned after
+Ruby&#8217;s own use of &quot;<tt>!</tt>&quot; as meaning <tt>not</tt>,
+<tt>assert!</tt> should be read &quot;assert not&quot;. While
+<tt>refute</tt> exists for the sake of those who find the use of a bang
+method for this purpose unsuited to them.
 </p>
-<h2>How It All Works</h2>
+<h2>How It Works</h2>
 <p>
 An Assertor essentially sits in wait for a method call (via
 method_missing). When that happens it applies the method to the original
@@ -212,13 +207,13 @@ Obviously using Assertor methods are whole lot more concise.
 <h1>Assert Method</h1>
 <h2>Compatible with Test::Unit</h2>
 <p>
-The +#assert+ method is designed to be backward compatible with the same
-method in +Test::Unit+.
+The <tt>assert</tt> method is designed to be backward compatible with the
+same method in <tt>Test::Unit</tt>.
 </p>
 <p>
-Using an argument, #assert will check that an argument evaluates to true.
-Optionally one can send along a meaningful message should the assertion
-fail.
+Using an argument, <tt>assert</tt> will check that an argument evaluates to
+true. Optionally one can send along a meaningful message should the
+assertion fail.
 </p>
 <pre>
   assert(true, &quot;Not true!&quot;)
@@ -229,9 +224,9 @@ fail.
 </pre>
 <h2>Assert with a Block</h2>
 <p>
-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.
+In addition <tt>assert</tt> has been extended to accept a block. Like the
+case of the argument, the block is expected to return something that
+evaluates as true.
 </p>
 <pre>
   assert do
@@ -256,23 +251,24 @@ block as a block argument.
 </pre>
 <h2>Antonyms for Assert</h2>
 <p>
-We can state the opposite assertion using #assert!
+We can state the opposite assertion using <tt>assert!</tt>.
 </p>
 <pre>
   10.assert! == 9
 </pre>
 <p>
-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,
+<tt>refute</tt>.
 </p>
 <pre>
   10.refute == 9
 </pre>
 <p>
-These terms can be used just as #assert is used in all examples, but with
-the opposite inference.
+These terms can be used just as <tt>assert</tt> is used in all examples,
+but with the opposite inference.
 </p>
 <p>
-Another way to get the opposite inference, is to use #not.
+Another way to get the opposite inference, is to use <tt>not</tt>.
 </p>
 <pre>
   10.assert.not == 9
@@ -286,24 +282,24 @@ Rather then the general form:
   x.assert.object_id == x.object_id
 </pre>
 <p>
-We can use Ruby&#8217;s own +equal?+ method.
+We can use Ruby&#8217;s own <tt>equal?</tt> method.
 </p>
 <pre>
   x.assert.equal?(x)
 </pre>
 <p>
-AE provides +identical?+ method as an alternative to make it a bit more
-clear.
+AE provides <tt>identical?</tt> method as an alternative to make it a bit
+more clear.
 </p>
 <pre>
   x.assert.identical?(x)
 </pre>
 <h2>Equality Assertions</h2>
 <p>
-The most common assertion is that of value equality (+==_), 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*.
+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 <em>type equality</em>.
 </p>
 <pre>
   17.assert.eql? 17
@@ -313,7 +309,7 @@ Equality*.
   end
 </pre>
 <p>
-And there is *Case Equality*.
+And there is <em>case equality</em>.
 </p>
 <pre>
   Numeric.assert === 3
@@ -323,11 +319,12 @@ 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
+method names are the same, they simply can take a block in place of an
 argument if need be.
 </p>
 <p>
-For *Value Equality*, +==+, the method is called +eq?+.
+For <em>value equality</em> (<tt>==</tt>), the method is called
+<tt>eq?</tt>.
 </p>
 <pre>
   10.assert.eq? do
@@ -345,7 +342,7 @@ And should it fail&#8230;
   end
 </pre>
 <p>
-For *Case Equality, +===+, it is +case?+.
+For <em>case equality</em> (<tt>===</tt>), it is <tt>case?</tt>.
 </p>
 <pre>
   Numeric.assert.case? do
@@ -388,7 +385,7 @@ with <tt>instance_eval</tt> makes it easy too.
 </pre>
 <h2>Catch/Try Assertions</h2>
 <p>
-Catch/Try throws can be tested via +Symbol#thrown?+.
+Catch/Try throws can be tested via <tt>Symbol#thrown?</tt>.
 </p>
 <pre>
   :hookme.assert.thrown? do
@@ -397,7 +394,7 @@ Catch/Try throws can be tested via +Symbol#thrown?+.
 </pre>
 <p>
 Alternatively, a lambda containing the potential throw can be the receiver
-using +throws?+.
+using <tt>throws?</tt>.
 </p>
 <pre>
   hook = lambda{ throw :hookme }
@@ -424,7 +421,7 @@ Ruby already provides the #nil? method.
   nil.assert.nil?
 </pre>
 <p>
-AE add true? and false? which acts accordingly.
+AE adds <tt>true?</tt> and <tt>false?</tt> which acts accordingly.
 </p>
 <pre>
   true.assert.true?
@@ -461,25 +458,60 @@ reusable assertions.
 
   &quot;abracarba&quot;.assert palindrome
 </pre>
+<h2>Verifying Object State</h2>
 <p>
-QED.
+NOTE: <em>This functionality is not currently supported, but is being
+considered for a future version.</em>
+</p>
+<p>
+If no block parameter is designated and the receiver differs from
+<tt>self</tt> in scope of the given block, then the block is evaluated in
+the scope of the receiver via <tt>instance_eval</tt>. This can be also be
+used to verify the state of an object.
+</p>
+<pre>
+  class X
+    attr :a
+    def initialize(a); @a = a; end
+  end
+
+  x = X.new(4)
+
+  x.must do
+    4 == @a
+  end
+</pre>
+<p>
+And should it fail&#8230;
+</p>
+<pre>
+  Assertion.assert.raised? do
+    x.must do
+      5 == @a
+    end
+  end
+</pre>
+<p>
+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.
 </p>
 
 <h1>Subjunctives</h1>
 <p>
-Okay. I can hear the BDDers rumbling, &quot;where&#8217;s the
-&#8216;should&#8217;?&quot; Well, AE has nothing against
-&#8216;should&#8217;, 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 <tt>should</tt> in a way analogous to RSpec&#8217;s use of
-<tt>it</tt>.
+Okay. I can hear the BDDers rumbling, &quot;where&#8217;s the should?&quot;
+AE has nothing against &quot;should&quot;, but there are different
+approaches for utilizing should nomenclature in specifications, and AE
+wants to be open to these techniques. One of which is how Shoulda
+(http://shoulda.rubyforge.org) utilizes <tt>should</tt> in a way analogous
+to RSpec&#8217;s use of <tt>it</tt>.
 </p>
 <p>
-Even so, AE provides a an optional mixin called Subjunctive which can be
-used to create assertor methods using English subjunctive terms such as
-<tt>should</tt> (or <tt>must</tt>, <tt>shall</tt> and <tt>will</tt>.
-Whatever you like.) To load this library use:
+Even so, AE provides a an optional mixin called <tt>Subjunctive</tt> which
+can be used to create assertor methods with English subjunctive terms, such
+as <tt>should</tt>, or <tt>must</tt>, <tt>shall</tt> and <tt>will</tt>. To
+load this library use:
 </p>
 <pre>
   require 'ae/subjunctive'
@@ -504,26 +536,26 @@ terms, <tt>should</tt> and <tt>must</tt> as optional add-ons.
 <p>
 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.
+almost exactly like <tt>assert</tt>.
 </p>
 <p>
 Keep in mind, AE &quot;conical&quot; functionality does not entail
-subjunctive forms, or <tt>should</tt> or <tt>must</tt> 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.
+subjunctive forms. These are simply options you can load via your
+<tt>test_helper.rb</tt>, or similar script, if you prefer these
+nomenclatures.
 </p>
 <h2>Fluent Notation and Antonyms</h2>
 <p>
-Like <tt>assert</tt>, <tt>should</tt> and <tt>must</tt> can be used as a
-higher order function.
+Like <tt>assert</tt>, <tt>should</tt> and <tt>must</tt> can be used as
+higher order functions.
 </p>
 <pre>
   4.should == 4
   4.must   == 4
 </pre>
 <p>
-With the antonym of +should!+ (read as &quot;should not&quot;) or
-<tt>shouldnt</tt>, and for <tt>must</tt>, +must!+ or <tt>wont</tt>.
+With the antonym of <tt>should!</tt> (read &quot;should not&quot;) or
+<tt>shouldnt</tt>, and for <tt>must</tt>, <tt>must!</tt> and <tt>wont</tt>.
 </p>
 <pre>
   4.should!  == 5
@@ -545,22 +577,30 @@ On occasions where the English readability of a specification is hindered,
 <p>
 The <tt>be</tt> method is the same as <tt>assert</tt> with the single
 exception that it will compare a lone argument to the receiver using
-+equate?+, unlike <tt>assert</tt> which simply check to see that the
++equate?+, unlike <tt>assert</tt> which simply checks to see that the
 argument evalutates as true.
 </p>
 <pre>
   10.should.be 10
   10.should.be 10.0
   10.should.be Numeric
+
+  Assertion.assert.raised? do
+    10.should.be &quot;40&quot;
+  end
 </pre>
 <h2>Indefinite Articles</h2>
 <p>
-Addtional anglogic forms are &#8216;a&#8217; and &#8216;an&#8217;,
-equivalent to &#8216;be&#8217; except that they use +case?+ instead of
-+equate?+,
+Addtional English forms are <tt>a</tt> and <tt>an</tt>, equivalent to
+<tt>be</tt> except that they use <tt>case?</tt> instead of <tt>equate?</tt>
+when acting on a single argument.
 </p>
 <pre>
   &quot;hi&quot;.must.be.a String
+
+  Assertion.assert.raised? do
+    /x/.must.be.a /x/
+  end
 </pre>
 <p>
 Otherwise they are interchangeble.
@@ -569,47 +609,13 @@ Otherwise they are interchangeble.
   &quot;hi&quot;.must.be.an.instance_of?(String)
 </pre>
 <p>
-The indefinite articles work well when a noun follow as an arguments.
+The indefinite articles work well when a noun follows as an arguments.
 </p>
 <pre>
   palindrome = lambda{ |x| x == x.reverse }
 
   &quot;abracarba&quot;.must.be.a palindrome
 </pre>
-<h2>Verifying Object State</h2>
-<p>
-The block notation of the subjunctive form is similar to <tt>assert</tt>,
-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.
-</p>
-<pre>
-  class X
-    attr :a
-    def initialize(a); @a = a; end
-  end
-
-  x = X.new(4)
-
-  x.must do
-    4 == @a
-  end
-</pre>
-<p>
-And should it fail&#8230;
-</p>
-<pre>
-  Assertion.assert.raised? do
-    x.must do
-      5 == @a
-    end
-  end
-</pre>
-<p>
-For some this might seem controversial &#8212;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.
-</p>
 <p>
 QED.
 </p>