ae 1.0.0

data/MANIFEST

@@ -0,0 +1,39 @@
+#!mast mast bin demo doc/qedoc lib meta test [A-Z]*
+demo
+demo/01_overview.rdoc
+demo/02_assertion.rdoc
+demo/03_assert.rdoc
+demo/04_subjunctive.rdoc
+doc/qedoc
+doc/qedoc/index.html
+doc/qedoc/jquery.js
+lib
+lib/ae
+lib/ae/assert.rb
+lib/ae/assertion.rb
+lib/ae/assertor.rb
+lib/ae/core_ext.rb
+lib/ae/subjunctive
+lib/ae/subjunctive/must.rb
+lib/ae/subjunctive/should.rb
+lib/ae/subjunctive.rb
+lib/ae.rb
+meta
+meta/authors
+meta/contact
+meta/created
+meta/description
+meta/homepage
+meta/license
+meta/package
+meta/project
+meta/released
+meta/repository
+meta/ruby
+meta/summary
+meta/title
+meta/version
+test
+LICENSE
+README
+HISTORY

data/README

@@ -0,0 +1,84 @@
+= A.E. -- Assertive Expressive
+
+* http://protuils.rubyforge.org/ae
+
+
+== DESCRIPTION
+
+Assertions Expressive (A.E.) is an assertions framework
+intended for reuse by any TDD, BDD or similar system.
+
+
+== FEATURES/ISSUES
+
+* 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.
+* Facets is an optional dependency; extensions are built-in.
+* Easily extensible allowing for alternate notations.
+* Eats it's own dog food.
+
+
+== RELEASE NOTES
+
+Please see HISTORY file.
+
+
+== SYNOPSIS
+
+AE defines the method +assert+. It's is compatible with the method
+as defined by Test::Unit and minitest, which verifies truth of a
+single argument (and can accept an optional failure message).
+
+  assert(true)
+
+In addition AE's +assert+ method has been extended to accept a block,
+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:
+
+  x.assert == y
+
+  a.assert.include? e
+
+  StandardError.assert.raised? do
+    ...
+  end
+
+And so forth. AE's abilities in this areas are quite extensive.
+You are encouraged to read the QEDocs to learn more.
+
+
+== HOW TO INSTALL
+
+To install with RubyGems simply open a console and type:
+
+  gem install ae
+
+Local installation requires Setup.rb (gem install setup),
+then download the tarball package and type:
+
+  tar -xvzf ae-1.0.0.tgz
+  cd ae-1.0.0.tgz
+  sudo setup.rb all
+
+Windows users use 'ruby setup.rb all'.
+
+
+== COPYRIGHTS & LICENSE
+
+Copyright (c) 2008,2009 Thomas Sawyer
+
+Unless otherwise provided for by the originating author, this
+program is distributed under the terms of the GPL v3 license.
+
+See LICENSE file for details.
+

data/demo/01_overview.rdoc

@@ -0,0 +1,97 @@
+= Introduction
+
+AE is an assertions framework for Ruby. It's designed
+around the concept of an Assertor. The Assertor is an
+Assertion Functor, or Higher-Order Function, which 
+reroutes method calls while monitoring them for failing
+conditions.
+
+
+== What's Provided
+
+Requiring the AE library.
+
+  require 'ae'
+
+Loads two classes, +Assertion+ and +Assertor+, the Kernel
+method +assert+ and it's ancillaries +assert!+ 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
+an instance of Assertion that is raised.
+
+  Assertion.assert.raised? do
+    msg = "my failure message"
+    assert false, msg
+  end
+
+Like any raised exception, the last Assertion message is available
+via +$!+.
+
+(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.)
+
+Assertions themsevles are not generally used in creating tests or
+behavior specifications. Rather they are used to create additonal
+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
+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.
+
+  assert(Assertor === assert)
+
+This allows us to write statements like:
+
+  1.assert == 1
+
+If the operation evaluates to false or nil, then an Assertion error
+is raised.
+
+  Assertion.assert.raised? do
+    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.
+
+
+== How It All 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:
+
+  raise Assertion.new("1 != 1") unless 1 == 1
+
+Instead of 
+
+  1.assert == 1
+
+Obviously using Assertor methods are whole lot more concise.
+

data/demo/02_assertion.rdoc

@@ -0,0 +1 @@
+

data/demo/03_assert.rdoc

@@ -0,0 +1,230 @@
+= Assert Method
+
+== Compatible with Test::Unit
+
+The +#assert+ method is designed to be backward compatible
+with the same method in +Test::Unit+.
+
+Using an argument, #assert will check that an argument evaluates
+to true. Optionally one can send along a meaningful message should
+the assertion fail.
+
+  assert(true, "Not true!")
+
+  Assertion.assert.raised? do
+    assert(false, "Not true!")
+  end
+
+
+== Assert with a Block
+
+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
+    true
+  end
+
+  Assertion.assert.raised? do
+    assert do
+      false
+    end
+  end
+
+We should also mention that, while probably not very useful, since
+the arity of a block can be checked, one can also pass the receiver
+into the block as a block argument.
+
+  "hi".assert do |s|
+    /h/ =~ s
+  end
+
+
+== Antonyms for Assert
+
+We can state the opposite assertion using #assert!
+
+  10.assert! == 9
+
+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,
+but with the opposite inference.
+
+Another way to get the opposite inference, is to use #not.
+
+  10.assert.not == 9
+
+
+== Identity Assertions
+
+Rather then the general form:
+
+  x = 10
+  x.assert.object_id == x.object_id
+
+We can use Ruby's own +equal?+ method.
+
+  x.assert.equal?(x)
+
+AE provides +identical?+ method as an alternative
+to make it a bit more clear.
+
+  x.assert.identical?(x)
+
+
+== Equality Assertions
+
+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*.
+
+  17.assert.eql? 17
+
+  Assertion.assert.raised? do
+    17.assert.eql? 17.0
+  end
+
+And there is *Case Equality*.
+
+  Numeric.assert === 3
+
+
+== Checking Equality with a Block
+
+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 *Value Equality*, +==+, the method is called +eq?+.
+
+  10.assert.eq? do
+    10.0
+  end
+
+And should it fail...
+
+  Assertion.assert.raised? do
+    10.assert.eq? do
+      20
+    end
+  end
+
+For *Case Equality, +===+, it is +case?+.
+
+  Numeric.assert.case? do
+    "3".to_i
+  end
+
+  Assertion.assert.raised? do
+    Numeric.assert.case? do
+      "3"
+    end
+  end
+
+
+== Exception Assertions
+
+Validating errors is easy too, as has already been shown
+in the document to verify assertion failures.
+
+  StandardError.assert.raised? do
+    unknown_method
+  end
+
+
+== Assertions on Object State
+
+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.
+
+  class X
+    attr :a
+    def initialize(a); @a = a; end
+  end
+
+  x = X.new(1)
+
+  x.assert.instance_eval do
+    @a == 1
+  end
+
+
+== Catch/Try Assertions
+
+Catch/Try throws can be tested via +Symbol#thrown?+.
+
+  :hookme.assert.thrown? do
+    throw :hookme
+  end
+
+Alternatively, a lambda containing the potential throw
+can be the receiver using +throws?+.
+
+  hook = lambda{ throw :hookme }
+  
+  hook.assert.throws?(:hookme)
+
+
+== Assertions on Proc Changes
+
+I have to admit I'm not sure how this is useful,
+but I found it in the Bacon API and ported it over
+just for sake of thoroughness.
+
+  a = 0
+
+  l = lambda{ a }
+
+  l.assert.change?{ a +=1 }
+
+
+== Assertion on literal True, False and Nil
+
+Ruby already provides the #nil? method.
+
+  nil.assert.nil?
+
+AE add true? and false? which acts accordingly.
+
+  true.assert.true?
+  false.assert.false?
+
+
+== Send Assertions
+
+Assert that a method can be successfully called.
+
+  "STRING".assert.send?(:upcase)
+
+
+== Numeric Delta and Epsilon
+
+You may wish to assert that a numeric value is with some
+range.
+
+  3.in_delta?(1,5)
+
+Or minimum range.
+
+  3.in_epsilon?(3,5)
+
+
+== Custom Lambda Assertions
+
+Passing a lambda to the subjunctive method, will use it as if it were
+a block of the method. This allows for a simple way to quickly
+create reusable assertions.
+
+  palindrome = lambda{ |x| x == x.reverse }
+
+  "abracarba".assert palindrome
+
+QED.
+