ae 1.2.2 → 1.2.3

data/HISTORY

@@ -1,5 +1,10 @@
 = RELEASE HISTORY
 
+== 1.2.3 / 2010-06-07
+
+This release is a quick fix, which adds a missing `require 'yaml'`.
+
+
 == 1.2.2 / 2010-06-06
 
 Version 1.2.2 simply add one new feature --the ability to

data/LICENSE

@@ -0,0 +1,23 @@
+The MIT License
+
+Copyright (c) 2008 Thomas Sawyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+

data/PROFILE

@@ -0,0 +1,18 @@
+--- 
+title  : AE
+summary: Assertive Expressive
+suite  : proutils
+contact: trans <transfire@gmail.com>
+created: 2008-08-17 09:00:06
+authors: Thomas Sawyer
+license: MIT
+
+description:
+  Assertive Expressive is an assertions library intended for reuse
+  by any TDD, BDD or the like system.
+
+resources:
+  homepage: http://proutils.github.com/ae
+  repository: git://github.com/proutils/ae.git
+
+copyright: Copyright (c) 2008 Thomas Sawyer

data/REQUIRE

@@ -0,0 +1,5 @@
+development:
+  - syckle
+
+development/test:
+  - qed

data/VERSION

@@ -0,0 +1,6 @@
+name : ae
+major: 1
+minor: 2
+patch: 3
+date : 2010-06-07
+

data/lib/ae.rb

@@ -1,3 +1,5 @@
+require 'yaml'
+
 module AE
   vers = YAML.load(File.read(File.dirname(__FILE__) + '/ae/version.yml'))
   VERSION = vers.values_at('major', 'minor', 'patch', 'state', 'build').compact.join('.')

data/lib/ae/version.yml

@@ -0,0 +1,6 @@
+name : ae
+major: 1
+minor: 2
+patch: 3
+date : 2010-06-07
+

data/qed/01_overview.rdoc

@@ -0,0 +1,92 @@
+= 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 <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 at the heart of AE. All other AE
+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
+    msg = "my failure message"
+    assert false, msg
+  end
+
+Like any raised exception, the last Assertion message is available
+via <tt>$!</tt>.
+
+(FYI, in Test::Unit the equivalent class was called +AssertionFailedError+.)
+
+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 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+, <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)
+
+Through the use of +method_missing+, the Assertor 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 <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 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/qed/02_assertion.rdoc

@@ -0,0 +1 @@
+

data/qed/03_assert.rdoc

@@ -0,0 +1,284 @@
+= Assert Method
+
+== Compatible with 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
+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 <tt>assert!</tt>.
+
+  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 <tt>equal?</tt> method.
+
+  x.assert.equal?(x)
+
+AE provides <tt>identical?</tt> 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 (<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 <i>type equality</i>.
+
+  17.assert.eql? 17
+
+  Assertion.assert.raised? do
+    17.assert.eql? 17.0
+  end
+
+And there is <i>case equality</i>.
+
+  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 names are the same, they simply
+can take a block in place of an argument if need be.
+
+For <i>value equality</i> (<tt>==</tt>), the method is called <tt>eq?</tt>.
+
+  10.assert.eq? do
+    10.0
+  end
+
+And should it fail...
+
+  Assertion.assert.raised? do
+    10.assert.eq? do
+      20
+    end
+  end
+
+== Case Equality
+
+For <i>case equality</i> (<tt>===</tt>), it is <tt>case?</tt>.
+
+  Numeric.assert.case? do
+    "3".to_i
+  end
+
+  Assertion.assert.raised? do
+    Numeric.assert.case? do
+      "3"
+    end
+  end
+
+
+== Regular Expressions
+
+Regular Expressions can be used to make assertions in much the same way as equality.
+
+  /i/.assert =~ "i"
+
+  Assertion.assert.raised? do
+    /i/.assert =~ "g"
+  end
+
+Conversely the String class recognizes the #=~ method as well.
+
+  "i".assert =~ /i/
+
+  Assertion.assert.raised? do
+    "i".assert =~ /g/
+  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 
+necessary. 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 <tt>Symbol#thrown?</tt>.
+
+  :hookme.assert.thrown? do
+    throw :hookme
+  end
+
+Alternatively, a lambda containing the potential throw
+can be the receiver using <tt>throws?</tt>.
+
+  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 adds <tt>true?</tt> and <tt>false?</tt> 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
+
+
+== 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.assert do
+    4 == @a
+  end
+
+And should it fail...
+
+  Assertion.assert.raised? do
+    x.assert 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.
+