= Subjunctives

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
+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.)
To load this library use:

  require 'ae/subjunctive'

Then all that is required it to define your 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.

  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.

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.


== Fluent Notation and Antonyms

Like +assert+, +should+ and +must+ can be used as a higher order function.

  4.should == 4
  4.must   == 4

With the antonym of +should!+ (read as "should not") or +shouldnt+, and for
+must+, +must!+ or +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.

  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
as true.

  10.should.be 10
  10.should.be 10.0
  10.should.be Numeric


== Indefinite Articles

Addtional anglogic forms are 'a' and 'an', equivalent to 'be' except
that they use +case?+ instead of +equate?+,

  "hi".must.be.a String

Otherwise they are interchangeble.

  "hi".must.be.an.instance_of?(String)

The indefinite articles work well when a noun follow 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.