doc/qedoc/index.html in ae-1.0.0 vs doc/qedoc/index.html in ae-1.1.0
- old
+ new
@@ -6,11 +6,11 @@
#container{ margin: 0 auto; width: 800px; }
/* 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; }
strong { font-weight: bold; }
tt { color: navy; }
@@ -112,62 +112,57 @@
<pre>
require 'ae'
</pre>
<p>
Loads two classes, <tt>Assertion</tt> and <tt>Assertor</tt>, the Kernel
-method <tt>assert</tt> and it’s ancillaries +assert!+ and
+method <tt>assert</tt> and it’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.
+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>
-<p>
-The <tt>Assertion</tt> class is at the heart of AE. All other AE method
-resolve by… 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.
-</p>
<pre>
Assertion.assert.raised? do
msg = "my failure message"
assert false, msg
end
</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 —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
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
</pre>
<p>
@@ -178,18 +173,18 @@
Assertion.assert.raised? do
1.assert == 2
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’s
-own use of +!+ as meaning <tt>not</tt>, +assert!+ should be read
-"assert not". While <tt>refute</tt> 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 <tt>refute</tt> are just like
+<tt>assert</tt> expect they purport the negative condition. Patterned after
+Ruby’s own use of "<tt>!</tt>" as meaning <tt>not</tt>,
+<tt>assert!</tt> should be read "assert not". 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
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
@@ -210,30 +205,30 @@
<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, "Not true!")
Assertion.assert.raised? do
assert(false, "Not true!")
end
</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
true
end
@@ -254,27 +249,28 @@
/h/ =~ s
end
</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
</pre>
<h2>Identity Assertions</h2>
@@ -284,52 +280,53 @@
<pre>
x = 10
x.assert.object_id == x.object_id
</pre>
<p>
-We can use Ruby’s own +equal?+ method.
+We can use Ruby’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
Assertion.assert.raised? do
17.assert.eql? 17.0
end
</pre>
<p>
-And there is *Case Equality*.
+And there is <em>case equality</em>.
</p>
<pre>
Numeric.assert === 3
</pre>
<h2>Checking Equality with a Block</h2>
<p>
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
10.0
end
@@ -343,11 +340,11 @@
20
end
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
"3".to_i
end
@@ -386,20 +383,20 @@
@a == 1
end
</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
throw :hookme
end
</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 }
hook.assert.throws?(:hookme)
@@ -422,11 +419,11 @@
</p>
<pre>
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?
false.assert.false?
</pre>
@@ -459,29 +456,64 @@
<pre>
palindrome = lambda{ |x| x == x.reverse }
"abracarba".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…
+</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, "where’s the
-‘should’?" Well, 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 <tt>should</tt> in a way analogous to RSpec’s use of
-<tt>it</tt>.
+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 is how Shoulda
+(http://shoulda.rubyforge.org) utilizes <tt>should</tt> in a way analogous
+to RSpec’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'
</pre>
<p>
@@ -502,30 +534,30 @@
require 'ae/subjunctive/must'
</pre>
<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 "conical" 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 "should not") or
-<tt>shouldnt</tt>, and for <tt>must</tt>, +must!+ or <tt>wont</tt>.
+With the antonym of <tt>should!</tt> (read "should not") or
+<tt>shouldnt</tt>, and for <tt>must</tt>, <tt>must!</tt> and <tt>wont</tt>.
</p>
<pre>
4.should! == 5
4.shouldnt == 5
@@ -543,74 +575,48 @@
end
</pre>
<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 "40"
+ end
</pre>
<h2>Indefinite Articles</h2>
<p>
-Addtional anglogic forms are ‘a’ and ‘an’,
-equivalent to ‘be’ 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>
"hi".must.be.a String
+
+ Assertion.assert.raised? do
+ /x/.must.be.a /x/
+ end
</pre>
<p>
Otherwise they are interchangeble.
</p>
<pre>
"hi".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 }
"abracarba".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…
-</p>
-<pre>
- Assertion.assert.raised? do
- x.must do
- 5 == @a
- end
- end
-</pre>
-<p>
-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.
-</p>
<p>
QED.
</p>