given_core 3.0.0.beta.4 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bb2de1d0ef168f096a0c169b3e7374c7ba30d785
-  data.tar.gz: e7ad7adad7bcafbedc3b7b71de4fa76a55d23c3f
+  metadata.gz: 0d0202f63aad80f12a4a00c7c783f12e34ee8370
+  data.tar.gz: d63f151d4f5c704956b42f6f6892398649b191c3
 SHA512:
-  metadata.gz: c5ba77de5d6d12fc167409b9f492e358619ddf7749c44158ffa67043480e6eea3b0cca50afe4c860a9a1393e049817f6c0ffb1ab69a8fc9e37a84b9160d34515
-  data.tar.gz: a4693b820a814b98a485e232b42dfee6533aa4f069d208f363abe140f1656b9636ffa9b656d926fe622ac02af35b0b92023d67097dc2537386827faefc8aaf0a
+  metadata.gz: 29034571bea4ef8f6526079d15b6c091c78e059c210ffe4e2ea9a4b537b8068562536236eb87a417c5773975e507ca82479e6baf21810c5e945d9c20f67cee6d
+  data.tar.gz: 374f4799fe58e262ea1c2aaed3cec7f37753248cb44ecd5ca4c120dc3386243fb2ebd9264b69993dd7ce99bf511c122254938eabc23f7d32b151f543494572c1

data/Gemfile

@@ -4,4 +4,3 @@ gem 'rake'
 gem 'rspec',    '>= 2.12'
 gem 'minitest', '>= 4.3'
 gem 'sorcerer', '>= 0.3.7'
-gem 'flexmock'

data/Gemfile.lock

@@ -2,14 +2,13 @@ GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.2.4)
-    flexmock (1.3.2)
     minitest (5.0.6)
     rake (10.0.4)
-    rspec (2.14.0)
+    rspec (2.14.1)
       rspec-core (~> 2.14.0)
       rspec-expectations (~> 2.14.0)
       rspec-mocks (~> 2.14.0)
-    rspec-core (2.14.0)
+    rspec-core (2.14.1)
     rspec-expectations (2.14.0)
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.14.1)
@@ -20,7 +19,6 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  flexmock
   minitest (>= 4.3)
   rake
   rspec (>= 2.12)

data/README.md

@@ -4,7 +4,7 @@
 | :----: |
 | [![Master Build Status](https://secure.travis-ci.org/jimweirich/rspec-given.png?branch=master)](https://travis-ci.org/jimweirich/rspec-given) |
 
-Covering rspec-given, minitest-given, and given-core, version 3.0.0.beta.1.
+Covering rspec-given, minitest-given, and given-core, version 3.0.0.
 
 rspec-given and minitest-given are extensions to your favorite testing
 framework to allow Given/When/Then notation when writing specs.
@@ -77,6 +77,44 @@ See
 and
 [example_helper.rb](https://github.com/jimweirich/rspec-given/blob/minispec/examples/example_helper.rb)
 
+## Installation
+
+### If you are using bundler
+
+Add `rspec-given` (or `minitest-given`) to the `:test` group in the `Gemfile`:
+
+```ruby
+group :test do
+  gem 'rspec-given'
+end
+```
+
+```ruby
+group :test do
+  gem 'minitest-given'
+end
+```
+
+Download and install:
+
+`$ bundle`
+
+Then just require `rspec/given` (or `minitest/given`) in the
+`spec_helper` of your project and it is ready to go.
+
+### If you are not using bundler
+
+Install the gem:
+
+`$ gem install rspec-given`
+
+or
+
+`$ gem install minitest-given`
+
+Then just require `rspec/given` (or `minitest/given`) in the
+`spec_helper` of your project and it is ready to go.
+
 ## Example
 
 Here is a specification written in the rspec-given framework:
@@ -575,7 +613,7 @@ like this is good:
 ```
 
 It is good to note that non-idempotent assertions will also cause
-problems with And clauses.
+problems with And and Invariant clauses.
 
 ### Mixing Natural Assertions and RSpec Assertions
 
@@ -665,7 +703,7 @@ fuzzy numbers.
 
 The RSpec matcher used for detecting exceptions will work with natural
 assertions out of the box. Just check for equality against the
-<code>have_failed</code> return value.
+<code>Failure()</code> method return value.
 
 For example, the following two Then clauses are equivalent:
 
@@ -715,9 +753,6 @@ Conover](http://rubygems.org/profiles/sconoversf).
 
 ## Configuration
 
-Just require 'rspec/given' in the spec helper of your project and it
-is ready to go.
-
 If the RSpec format option document, html or textmate is chosen,
 RSpec/Given will automatically add additional source code information to
 the examples to produce better looking output. If you don't care about
@@ -751,8 +786,11 @@ License. See the MIT-LICENSE file in the source distribution.
 
   * Support for minitest added.
 
-  * Gems rspec-given and minitest-given both use the core
-    functionality of gem given_core.
+  * Introduced gem given_core to contain the common logic between the
+    RSpec and Minitest versions. Both the rspec-given gem and the
+    minitest-given gem have a dependency on given_core.
+
+  * Natural assertions are now enabled by default.
 
 * Version 2.4.4
 

data/README.old

@@ -0,0 +1,829 @@
+# Given/When/Then for RSpec and Minitest
+
+| Master | Minispec |
+| :----: | :----: |
+| [![Master Build Status](https://secure.travis-ci.org/jimweirich/rspec-given.png?branch=master)](https://travis-ci.org/jimweirich/rspec-given) | [![Minispec Build Status](https://secure.travis-ci.org/jimweirich/rspec-given.png?branch=minispec)](https://travis-ci.org/jimweirich/rspec-given) |
+
+Covering rspec-given, minitest-given, and given-core, version 3.0.0.beta.1.
+
+rspec-given and minitest-given are extensions to your favorite testing
+framework to allow Given/When/Then notation when writing specs.
+
+# Why Given/When/Then
+
+RSpec has done a great job of making specifications more readable for
+humans. However, I really like the given/when/then nature of Cucumber
+stories and would like to follow the same structure in my unit tests.
+rspec-given (and now minitest-given) allows a simple given/when/then
+structure RSpec specifications.
+
+## Status
+
+* rspec-given is ready for production use.
+* minitest-given is experimental.
+
+### RSpec/Given
+
+The rspec-given gem is the original given/when/then extension for
+RSpec. It now depends on a given_core gem for the basic functionality
+and then adds the RSpec specific code.
+
+* rspec-given now requires RSpec version 2.12 or better.
+
+### Minitest/Given
+
+A new minitest-given gem allows Given/When/Then notation directly in
+Minitest::Spec specifications.
+
+To use minitest-given, just place the following require at the top of
+the file (or in a convenient spec_helper).
+
+```ruby
+require 'minitest/given'
+```
+
+All the features of rspec-given are available in minitest-given.
+
+When switching from RSpec/Given to Minitest/Given, here are some
+things to watch out for:
+
+* You need to use Minitest version 4.3 or better (yes, Minitest 5.x
+  should work as well).
+
+* Minitest/Given adds the missing "context" block to Minitest::Spec.
+
+* Only one before block is allowed in any given Minitest::Spec
+  describe block. This doesn't effect the number of Givens you are
+  allowed to use, but it may surprise if you are use to RSpec.
+
+### Auto Selecting
+
+If you use natural assertions exclusively in your specs, it's quite
+possible to write specs that run under both RSpec and Minitest::Spec.
+
+Use this at the start of your spec file:
+
+```ruby
+if defined?(RSpec)
+  require 'rspec/given'
+else
+  require 'minitest/autorun'
+  require 'minitest/given'
+end
+```
+
+See
+[stack_spec.rb](https://github.com/jimweirich/rspec-given/blob/minispec/examples/stack/stack_spec.rb)
+and
+[example_helper.rb](https://github.com/jimweirich/rspec-given/blob/minispec/examples/example_helper.rb)
+
+## Installation
+
+### If you are using bundler
+
+Add `rspec-given` (or `minitest-given`) to the `:test` group in the `Gemfile`:
+
+```ruby
+group :test do
+  gem 'rspec-given'
+end
+```
+
+```ruby
+group :test do
+  gem 'minitest-given'
+end
+```
+
+Download and install:
+
+`$ bundle`
+
+Then just require `rspec/given` (or `minitest/given`) in the
+`spec_helper` of your project and it is ready to go.
+
+### If you are not using bundler
+
+Install the gem:
+
+`$ gem install rspec-given`
+
+or
+
+`$ gem install minitest-given`
+
+Then just require `rspec/given` (or `minitest/given`) in the
+`spec_helper` of your project and it is ready to go.
+
+## Example
+
+Here is a specification written in the rspec-given framework:
+
+```ruby
+require 'rspec/given'
+require 'spec_helper'
+require 'stack'
+
+describe Stack do
+  def stack_with(initial_contents)
+    stack = Stack.new
+    initial_contents.each do |item| stack.push(item) end
+    stack
+  end
+
+  Given(:stack) { stack_with(initial_contents) }
+  Invariant { stack.empty? == (stack.depth == 0) }
+
+  context "with no items" do
+    Given(:initial_contents) { [] }
+    Then { stack.depth == 0 }
+
+    context "when pushing" do
+      When { stack.push(:an_item) }
+
+      Then { stack.depth == 1 }
+      Then { stack.top == :an_item }
+    end
+
+    context "when popping" do
+      When(:result) { stack.pop }
+      Then { result == Failure(Stack::UnderflowError, /empty/) }
+    end
+  end
+
+  context "with one item" do
+    Given(:initial_contents) { [:an_item] }
+
+    context "when popping" do
+      When(:pop_result) { stack.pop }
+
+      Then { pop_result == :an_item }
+      Then { stack.depth == 0 }
+    end
+  end
+
+  context "with several items" do
+    Given(:initial_contents) { [:second_item, :top_item] }
+    Given!(:original_depth) { stack.depth }
+
+    context "when pushing" do
+      When { stack.push(:new_item) }
+
+      Then { stack.top == :new_item }
+      Then { stack.depth == original_depth + 1 }
+    end
+
+    context "when popping" do
+      When(:pop_result) { stack.pop }
+
+      Then { pop_result == :top_item }
+      Then { stack.top == :second_item }
+      Then { stack.depth == original_depth - 1 }
+    end
+  end
+end
+```
+
+Let's talk about the individual statements used in the Given
+framework.
+
+### Given
+
+The _Given_ section specifies a starting point, a set of preconditions
+that must be true before the code under test is allowed to be run.  In
+standard test frameworks the preconditions are established with a
+combination of setup methods (or :before actions in RSpec) and code in
+the test.
+
+In the example code above the preconditions are started with _Given_
+statements.  A top level _Given_ (that applies to the entire describe
+block) says that one of the preconditions is that there is a stack
+with some initial contents.
+
+Note that initial contents are not specified in the top level describe
+block, but are given in each of the nested contexts.  By pushing the
+definition of "initial_contents" into the nested contexts, we can vary
+them as needed for that particular context.
+
+A precondition in the form "Given(:var) {...}" creates an accessor
+method named "var".  The accessor is lazily initialized by the code
+block.  If you want a non-lazy given, use "Given!(:var) {...}".
+
+A precondition in the form "Given {...}" just executes the code block
+for side effects.  Since there is no accessor, the code block is
+executed immediately (i.e. no lazy evaluation).
+
+The preconditions are run in order of definition.  Nested contexts
+will inherit the preconditions from the enclosing context, with outer
+preconditions running before inner preconditions.
+
+#### Given examples:
+
+```ruby
+    Given(:stack) { Stack.new }
+```
+
+The block for the given clause is lazily run and its value bound to
+'stack' if 'stack' is ever referenced in the test.
+The first reference to 'stack' in the specification will cause the
+code block to execute. Futher references to 'stack' will reuse the
+previously generated value.
+
+```ruby
+    Given!(:original_size) { stack.size }
+```
+
+The code block is run unconditionally once before each test and the
+value of the block is bound to 'original_size'.  This form is useful
+when you want to record the value of something that might be affected
+by the When code.
+
+```ruby
+    Given { stack.clear }
+```
+
+The block for the given clause is run unconditionally once before each
+test. This form of given is used for code that is executed for side
+effects.
+
+### When
+
+The _When_ clause specifies the code to be tested ... oops, excuse me
+... specified.  After the preconditions in the given section are met,
+the when code block is run.
+
+In general there should not be more than one _When_ clause for a given
+direct context. However, a _When_ in an outer context will be run
+after all the _Givens_ but before the inner _When_. You can think of
+an outer _When_ as setting up additional given state for the inner
+_When_.
+
+E.g.
+
+```ruby
+    context "outer context" do
+      When { code specified in the outer context }
+      Then { assert something about the outer context }
+
+      context "inner context" do
+
+        # At this point, the _When_ of the outer context
+        # should be treated as a _Given_ of the inner context
+
+        When { code specified in the inner context }
+        Then { assert something about the inner context }
+      end
+    end
+```
+
+#### When examples:
+
+```ruby
+    When { stack.push(:item) }
+```
+
+The code block is executed once per test.  The effect of the _When{}_
+block is very similar to _Given{}_.  However, When is used to identify
+the particular code that is being specified in the current context or
+describe block.
+
+```ruby
+    When(:result) { stack.pop }
+```
+
+The code block is executed once per test and the value of the code
+block is bound to 'result'.  Use this form when the code under test
+returns a value that you wish to interrogate in the _Then_ code.
+
+If an exception occurs during the execution of the block for the When
+clause, the exception is caught and a failure object is bound to
+'result'. The failure can be checked in a then block with the
+'have_failed' matcher.
+
+The failure object will rethrow the captured exception if anything
+other than have_failed matcher is used on the failure object.
+
+For example, if the stack is empty when it is popped, then it is
+reasonable for pop to raise an UnderflowError. This is how you might
+specify that behavior:
+
+```ruby
+    When(:result) { stack.pop }
+    Then { result.should have_failed(UnderflowError, /empty/) }
+```
+
+Note that the arguments to the 'have_failed' matcher are the same as
+those given to the standard RSpec matcher 'raise_error'.
+
+### Then
+
+The _Then_ clauses are the postconditions of the specification. These
+then conditions must be true after the code under test (the _When_
+clause) is run.
+
+The code in the block of a _Then_ clause should be a single _should_
+assertion. Code in _Then_ clauses should not have any side effects.
+
+Let me repeat that: <b>_Then_ clauses should not have any side
+effects!</b> _Then_ clauses with side effects are erroneous. _Then_
+clauses need to be idempotent, so that running them once, twice, a
+hundred times, or never does not change the state of the program. (The
+same is true of _And_ and _Invariant_ clauses).
+
+In RSpec terms, a _Then_ clause forms a RSpec Example that runs in the
+context of an Example Group (defined by a describe or context clause).
+
+Each Example Group must have at least one _Then_ clause, otherwise
+there will be no examples to be run for that group. If all the
+assertions in an example group are done via Invariants, then the group
+should use an empty _Then_ clause, like this:
+
+```ruby
+    Then { }
+```
+
+#### Then examples:
+
+```ruby
+    Then { stack.empty? }
+```
+
+After the related block for the _When_ clause is run, the stack should
+be empty. If it is not empty, the test will fail.
+
+### And
+
+The _And_ clause is similar to _Then_, but does not form its own RSpec
+example. This means that _And_ clauses reuse the setup from a sibling
+_Then_ clause. Using a single _Then_ and multiple _And_ clauses in an
+example group means the setup for that group is run only once (for the
+_Then_ clause) and reused for all the _And_ clauses. This can be a
+significant speed savings where the setup for an example group is
+expensive.
+
+Some things to keep in mind about _And_ clauses:
+
+* There must be at least one _Then_ in the example group and it must
+  be declared before the _And_ clauses. Forgetting the _Then_ clause
+  is an error.
+
+* The code in the _And_ clause is run immediately after the first
+  (executed) _Then_ of an example group.
+
+* An assertion failure in a _Then_ clause or an _And_ clause will
+  cause all the subsequent _And_ clauses to be skipped.
+
+* Since _And_ clauses do not form their own RSpec examples, they are
+  not represented in the formatted output of RSpec. That means _And_
+  clauses do not produce dots in the Progress format, nor do they
+  appear in the documentation, html or textmate formats (options
+  -fhtml, -fdoc, or -ftextmate).
+
+* Like _Then_ clauses, _And_ clauses must be idempotent. That means
+  they should not execute any code that changes global program state.
+  (See the section on the _Then_ clause).
+
+The choice to use an _And_ clause is primarily a speed consideration.
+If an example group has expensive setup and there are a lot of _Then_
+clauses, then choosing to make some of the _Then_ clauses into _And_
+clauses will speed up the spec. Otherwise it is probably better to
+stick with _Then_ clauses.
+
+#### Then/And examples:
+
+```ruby
+  Then { pop_result == :top_item }           # Required
+  And  { stack.top == :second_item }         # No Setup rerun
+  And  { stack.depth == original_depth - 1 } # ... for these
+```
+
+### Invariant
+
+The _Invariant_ clause is a new idea that doesn't have an analog in
+RSpec or Test::Unit. The invariant allows you specify things that must
+always be true in the scope of the invariant. In the stack example, the method
+<tt>empty?</tt> is defined in term of <tt>size</tt>.
+
+```ruby
+  Invariant { stack.empty? == (stack.depth == 0) }
+```
+
+This invariant states that <code>empty?</code> is true if and only if
+the stack depth is zero, and that assertion is checked at every _Then_
+clause that is in the same scope.
+
+You can conceptually think of an _Invariant_ clause as a _Then_ block
+that automatically gets added to every _Then_ within its scope.
+Invariants nested within a context only apply to the _Then_ clauses
+that are in the scope of that context.
+
+Invariants that reference a _Given_ precondition accessor must only be
+used in contexts that define that accessor.
+
+Notes:
+
+* Since Invariants do not form their own RSpec example, they are not
+  represented in the RSpec formatted output (e.g. the '--format html'
+  option).
+
+## Execution Ordering
+
+When running the test for a specific _Then_ clause, the following will
+be true:
+
+* The non-lazy _Given_ clauses will be run in the order that they are
+  specified, from the outermost scope to the innermost scope
+  containing the _Then_. (The lazy _Given_ clauses will be run upon
+  demand).
+
+* All of the _Given_ clauses in all of the relevant scopes will run
+  before the first (outermost) _When_ clause in those same scopes.
+  That means that the _When_ code can assume that the givens have been
+  established, even if the givens are in a more nested scope than the
+  When.
+
+* _When_ clauses and RSpec _before_ blocks will be executed in the
+  order that they are specified, from the outermost block to the
+  innermost block. This makes _before_ blocks an excellent choice when
+  writing narrative tests to specify actions that happen between the
+  "whens" of a narrative-style test.
+
+Note that the ordering between _Given_ clauses and _before_ blocks are
+not strongly specified. Hoisting a _When_ clause out of an inner scope
+to an outer scope may change the order of execution between related
+_Given_ clauses and any _before_ blocks (hoisting the _When_ clause
+might cause the related _Given_ clauses to possibly run earlier).
+Because of this, do not split order dependent code between _Given_
+clauses and _before_ blocks.
+
+## Natural Assertions
+
+RSpec/Given now supports the use of "natural assertions" in _Then_,
+_And_, and _Invariant_ blocks. Natural assertions are just Ruby
+conditionals, without the _should_ or _expect_ methods that RSpec
+provides. Here are the Then/And examples showing natural assertions:
+
+### Using Natural Assertions
+
+```ruby
+  Then { stack.top == :second_item }
+  Then { stack.depth == original_depth - 1 }
+  Then { result == Failure(Stack::UnderflowError, /empty/) }
+```
+
+### Using RSpec expect().to
+
+```ruby
+  Then { expect(stack.top).to eq(:second_item) }
+  Then { expect(stack.depth).to eq(original_depth - 1) }
+  Then { expect(result).to have_failed(Stack::UnderflowError, /empty/) }
+```
+
+### Using Minitest asserts
+
+```ruby
+  Then { assert_equal :second_item, stack.top }
+  Then { assert_equal original_depth - 1, stack.depth }
+  Then {
+    assert_raises(Stack::UnderflowError, /empty/) do
+      result.call()
+    end
+  }
+```
+
+### Using Minitest expectations
+
+```ruby
+  Then { stack.top.must_equal :second_item }
+  Then { stack.depth.must_equal original_depth - 1}
+  Then { result.must_raise(Stack::UnderflowError, /empty/) }
+```
+
+### Disabling Natural Assertions
+
+Natural assertions may be disabled, either globally or on a per
+context basis. See the **configuration** section below to see how to
+disable natural assertions project wide.
+
+Here's a heads up: If you use natural assertions, but configure Given
+to disable them, then all your specs will mysteriously pass. This is
+why the **red** part of _Red/Green/Refactor_ is so important.
+
+### Failure Messages with Natural Assertions
+
+Since natural assertions do not depend upon matchers, you don't get
+customized error messages from them. What you _do_ get is a complete
+analsysis of the expression that failed.
+
+For example, given the following failing specification:
+
+```ruby
+  Given.use_natural_assertions
+
+  describe "Natural Assertions" do
+    Given(:foo) { 1 }
+    Given(:bar) { 2 }
+    Then { foo + bar == 2 }
+  end
+```
+
+You would get:
+
+```
+  1) Natural Assertions
+     Failure/Error: Then { foo + bar == 2 }
+       Then expression failed at /Users/jim/working/git/rspec-given/examples/failing/sample_spec.rb:6
+       expected: 3
+       to equal: 2
+         false   <- foo + bar == 2
+         3       <- foo + bar
+         1       <- foo
+         2       <- bar
+     # ./examples/failing/sample_spec.rb:6:in `block in Then'
+```
+
+Notice how the failing expression "<code>foo+bar == 2</code>" was
+broken down into subexpressions and values for each subexpression.
+This gives you all the information you need to figure out exactly what
+part of the expression is causing the failure.
+
+Natural assertions will give additional information (e.g. "expected:
+3 to equal: 2") for top level expressions involving any of the
+comparison operators (==, !=, <, <=, >, >=) or matching operators (=~,
+!~).
+
+### Checking for exceptions with Natural Assertions
+
+If you wish to see if the result of a _When_ clause is an exception,
+you can use the following:
+
+```ruby
+    When(:result) { stack.pop }
+    Then { result == Failure(UnderflowError, /empty/) }
+```
+
+The <code>Failure()</code> method accepts the same arguments as
+<code>have_failed</code> and <code>raise_error</code>.
+
+### Caveats on Natural Assertions
+
+Keep the following in mind when using natural assertions.
+
+* Only a single expression/assertion per _Then_. The single expression
+  of the _Then_ block will be considered when determining pass/fail
+  for the assertion. If you _want_ to express a complex condition for
+  the _Then_, you need to use ||, && or some other logical operation
+  to join the conditions into a single expression (and the failure
+  message will break down the values for each part).
+
+* Then clauses need be **idempotent**. This is true in general, but it
+  is particularly important for natural assertions to obey this
+  restriction. This means that assertions in a Then clause should not
+  change anything. Since the Natural Assertion error message contains
+  the values of all the subexpressions, the expression and its
+  subexpressions will be evaluated multiple times. If the Then clause
+  is not idempotent, you will get changing answers as the
+  subexpressions are evaluated.
+
+That last point is important. If you write code like this:
+
+```ruby
+  # DO NOT WRITE CODE LIKE THIS
+  context "Incorrect non-idempotent conditions" do
+    Given(:ary) { [1, 2, 3] }
+    Then { ary.delete(1) == nil }
+  end
+```
+
+Then the assertion will fail (because <code>ary.delete(1)</code> will
+initially return 1). But when the error message is formated, the
+system reports that <code>ary.delete(1)</code> returns nil. You will
+scratch your head over that for a good while.
+
+Instead, move the state changing code into a _When(:result)_ block, then
+assert what you need to about :result. Something
+like this is good:
+
+```ruby
+  context "Correct idempotent conditions" do
+    Given(:ary) { [1, 2, 3] }
+    When(:result) { ary.delete(1) }
+    Then { result == nil }
+  end
+```
+
+It is good to note that non-idempotent assertions will also cause
+problems with And and Invariant clauses.
+
+### Mixing Natural Assertions and RSpec Assertions
+
+Natural assertions, RSpec should assertions and Minitest assertions
+can be intermixed in a single test suite, even within a single
+context.
+
+```ruby
+  context "Outer" do
+    context "Inner" do
+      Then { a == b }               # Natural Assertions
+      Then { a.should == b }        # RSpec style
+      Then { expect(a).to eq(b) }   # RSpec style
+      Then { assert_equal b, a }    # Minitest style
+      Then { a.must_equal b }       # Minitest style
+    end
+
+    context "Disabled" do
+      use_natural_assertions false
+    end
+  end
+```
+
+Both the _Outer_ and _Inner_ contexts will use natural assertions. The
+_Disabled_ context overrides the setting inherited from _Outer_ and
+will not process natural assertions.
+
+See the **configuration** section below to see how to disable natural
+assertions project wide.
+
+### Matchers and Natural Assertions
+
+In RSpec, matchers are used to provide nice, readable error messages
+when an assertion is not met. Natural assertions provide
+self-explanatory failure messages for most things without requiring
+any special matchers from the programmer.
+
+In the rare case that some extra information would be helpful, it is
+useful to create special objects that respond to the == operator.
+
+#### Asserting Nearly Equal with Fuzzy Numbers
+
+Operations on floating point numbers rarely create numbers that are
+exactly equal, therefore it is useful to assert that two floating
+point numbers are nearly equal. We do that by creating a fuzzy number
+that has a looser interpretation of what it means to be equal.
+
+For example, the following asserts that the square root of 10 is about
+3.1523 with an accuracy of 1 percent.
+
+```ruby
+    Then { Math.sqrt(10) == about(3.1623).percent(1) }
+```
+
+As long as the real value of <code>Math.sqrt(10)</code> is within plus
+or minus 1% of 3.1623 (i.e. 3.1623 +/- 0.031623), then the assertion
+will pass.
+
+There are several ways of creating fuzzy numbers:
+
+* <code>about(n).delta(d)</code> -- A fuzzy number matching the range
+  (n-d)..(n+d)
+
+* <code>about(n).percent(p)</code> -- A fuzzy number matching the
+  range (n-(n*p/100)) .. (n+(n*p/100))
+
+* <code>about(n).epsilon(neps)</code> -- A fuzzy number matching the
+  range (n-(neps*e)) .. (n+(neps*e)), where e is the difference
+  between 1.0 and the next smallest floating point number.
+
+* <code>about(n)</code> -- Same as <code>about(n).epsilon(10)</code>.
+
+When the file <code>given/fuzzy_shortcuts</code> is required,
+the following unicode shortcut methods are added to Numeric to create
+fuzzy numbers.
+
+* <code>n.±(del)</code> is the same as <code>about(n).delta(del)</code>
+
+* <code>n.‰(percentage)</code> is the same as <code>about(n).percent(percentage)</code>
+
+* <code>n.€(neps)</code> is the same as <code>about(n).epsilon(neps)</code>
+
+* <code>n.±</code>, <code>n.‰</code>, and <code>n.€</code> are all
+  the same as <code>about(n)</code>
+
+#### Detecting Exceptions
+
+The RSpec matcher used for detecting exceptions will work with natural
+assertions out of the box. Just check for equality against the
+<code>Failure()</code> method return value.
+
+For example, the following two Then clauses are equivalent:
+
+```ruby
+    # Using an RSpec matcher
+    Then { result.should have_failed(StandardError, /message/) }
+
+    # Using natural assertions
+    Then { result == Failure(StandardError, /message/) }
+```
+
+### Processing Natural Assertions
+
+When natural assertions are enabled, they are only used if all of the
+following are true:
+
+1. The block does not throw an RSpec assertion failure (or any other
+   exception for that matter).
+
+1. The block returns false (blocks that return true pass the
+   assertion and don't need a failure message).
+
+1. The block does not use the native frameworks assertions or
+   expectations (e.g. RSpec's _should_ or _expect_ methods, or
+   Minitest's _assert\_xxx_ or _must\_xxx_ methods).
+
+Detecting that last point (the use of _should_ and _expect_) is done
+by modifying the RSpec runtime to report uses of _should_ and
+_expect_.
+
+### Platform Support
+
+Natural assertions use the Ripper library to parse the failing
+condition and find all the sub-expression values upon a failure.
+Currently Ripper is not fully supported on JRuby 1.7.4. Charles Nutter
+has said that Ripper support is coming soon and may arrive soon. Until
+then, natural assertions are disabled when running under JRuby. Never
+fear, JRuby supports all the other features of rspec-given and will
+work just fine.
+
+### Further Reading
+
+Natural assertions were inspired by the [wrong assertion
+library](http://rubygems.org/gems/wrong) by [Alex
+Chaffee](http://rubygems.org/profiles/alexch) and [Steve
+Conover](http://rubygems.org/profiles/sconoversf).
+
+## Configuration
+
+If the RSpec format option document, html or textmate is chosen,
+RSpec/Given will automatically add additional source code information to
+the examples to produce better looking output. If you don't care about
+the pretty output and wish to disable source code caching
+unconditionally, then add the following line to your spec helper file:
+
+```ruby
+    Given.source_caching_disabled = true
+```
+
+Natural assertions are disabled by default. To globally configure
+natural assertions, add one of the following lines to your spec_helper
+file:
+
+```ruby
+    Given.use_natural_assertions         # Enable natural assertions
+    Given.use_natural_assertions true    # Same as above
+    Given.use_natural_assertions false   # Disable natural assertions
+    Given.use_natural_assertions :always # Always process natural assertions
+                                         # ... even when should/expect are detected
+```
+
+# License
+
+rspec-given, minitest-given and given_core are available under the MIT
+License. See the MIT-LICENSE file in the source distribution.
+
+# History
+
+* Version 3.0.0
+
+  * Support for minitest added.
+
+  * Introduced gem given_core to contain the common logic between the
+    RSpec and Minitest versions. Both the rspec-given gem and the
+    minitest-given gem have a dependency on given_core.
+
+  * Natural assertions are now enabled by default.
+
+* Version 2.4.4
+
+  * Support for RSpec 2.13 added.
+
+* Version 2.4.3
+
+  * Better natural assertion messages when dealing with multi-line
+    output.
+
+* Version 2.4.2
+
+  * Minor adjustment to natural assertion error messages to better
+    handle multi-line values.
+
+  * Remove flog, flay and other development tools from the bundle and
+    gemspec. The Rakefile was updated to suggest installing them if
+    they are not there.
+
+* Version 2.4.1
+
+  * Fix bug where constants from nested modules were not properly
+    accessed.
+
+* Version 2.4.0
+
+  * Add fuzzy number helper methods (with unicode method shortcuts).
+
+  * Fix bug caused by blank lines in Thens.
+
+# Links
+
+* Github: [https://github.com/jimweirich/rspec-given](https://github.com/jimweirich/rspec-given)
+* Clone URL: git://github.com/jimweirich/rspec-given.git
+* Bug/Issue Reporting: [https://github.com/jimweirich/rspec-given/issues](https://github.com/jimweirich/rspec-given/issues)
+* Continuous Integration: [http://travis-ci.org/#!/jimweirich/rspec-given](http://travis-ci.org/#!/jimweirich/rspec-given)

data/lib/given/binary_operation.rb

@@ -0,0 +1,33 @@
+module Given
+
+  class BinaryOperation
+    BINARY_EXPLAINATIONS = {
+      :== => "to equal",
+      :!= => "to not equal",
+      :<  => "to be less than",
+      :<= => "to be less or equal to",
+      :>  => "to be greater than",
+      :>= => "to be greater or equal to",
+      :=~ => "to match",
+      :!~ => "to not match",
+    }
+
+    attr_reader :left, :operator, :right
+
+    def initialize(left, operator, right)
+      @left = left
+      @operator = operator
+      @right = right
+    end
+
+    def explain
+      BINARY_EXPLAINATIONS[operator]
+    end
+
+    def self.parse(sexp)
+      return nil unless sexp.first == :binary
+      new(sexp[1], sexp[2], sexp[3])
+    end
+  end
+
+end

data/lib/given/evaluator.rb

@@ -27,6 +27,10 @@ module Given
       EvalErr.new("#{ex.class}: #{ex.message}")
     end
 
+    def location
+      @example.class._Gvn_location_of(@block)
+    end
+
     private
 
     def eval_in_context(exp_string)

data/lib/given/extensions.rb

@@ -4,9 +4,18 @@ require 'given/failure'
 
 module Given
 
-  # Provide run-time methods to support Given infrastructure. All the
-  # methods in this module are considered private and
-  # implementation-specific.
+  # Provide run-time instance methods to support Given infrastructure.
+  # All the methods in this module are considered private and
+  # implementation-specific, and should not be directly called by the
+  # application developer.
+  #
+  # By convention, these private instance specific methods are
+  # prefixed with _gvn_ to avoid name collisions with application
+  # methods defined in a spec.
+  #
+  # (Note that private class methods are prefixed with _Gvn_ and
+  # private instance methods are prefixed with _gvn_).
+  #
   module InstanceExtensions   # :nodoc:
 
     # List of containing contexts in order from innermost to
@@ -96,15 +105,15 @@ module Given
 
     # Evaluate a Then, And, or Invariant assertion.
     def _gvn_evaluate(clause_type, block)   # :nodoc:
-      Given.framework.start_evaluation
+      Given.start_evaluation
       passed = instance_eval(&block)
-      if ! Given.framework.explicit_assertions? && _gvn_na_configured?
+      if ! Given.explicit_assertions? && _gvn_na_configured?
         _gvn_naturally_assert(clause_type, block, passed)
       end
     end
 
     def _gvn_naturally_assert(clause_type, block, passed)
-      Given.framework.count_assertion
+      Given.count_assertion
       unless passed
         nassert = NaturalAssertion.new(clause_type, block, self, self.class._Gvn_lines)
         Given.fail_with nassert.message if _gvn_need_na_message?(nassert)
@@ -112,6 +121,15 @@ module Given
     end
   end
 
+  # Provide run-time class methods to support Given infrastructure.
+  # Methods that begin with _Gvn_ are considered private and
+  # implementation specific, and should not be directly called by
+  # appliation code. Other methods without the _Gvn_ prefix are public
+  # and intended for use by the application developer.
+  #
+  # (Note that private class methods are prefixed with _Gvn_ and
+  # private instance methods are prefixed with _gvn_).
+  #
   module ClassExtensions
 
     # List of all givens directly in the current describe/context
@@ -204,13 +222,9 @@ module Given
     # in a Failure object.
     def _Gvn_when_actions_with_capture(name, block) # :nodoc:
       let(name) do
-        begin
+        Failure.capture(Given.pending_error) do
           _gvn_establish_givens
           instance_eval(&block)
-        rescue Given.pending_error => ex
-          raise
-        rescue Exception => ex
-          Failure.new(ex)
         end
       end
       _Gvn_before do __send__(name) end
@@ -226,13 +240,18 @@ module Given
     #   Then { ... assertion ... }
     #
     def Then(&block)
-      file, line = eval "[__FILE__, __LINE__]", block.binding
+      file, line = _Gvn_location_of(block)
       description = _Gvn_lines.line(file, line) unless Given.source_caching_disabled
       cmd = description ? "it(description)" : "specify"
       eval %{#{cmd} do _gvn_then(&block) end}, binding, file, line
       _Gvn_context_info[:then_defined] = true
     end
 
+    # Return file and line number where the block is defined.
+    def _Gvn_location_of(block)
+      eval "[__FILE__, __LINE__]", block.binding
+    end
+
     # Establish an invariant that must be true for all Then blocks
     # in the current (and nested) scopes.
     def Invariant(&block)

data/lib/given/failure.rb

@@ -6,20 +6,32 @@ module Given
   class Failure < BasicObject
     undef_method :==, :!=, :!
 
-    def must_raise(*args)
-      ::Minitest::Spec.current.assert_raises(*args) do
-        die
+    # Evaluate a block. If an exception is raised, capture it in a
+    # Failure object. Explicitly listed exceptions are passed thru
+    # without capture.
+    def self.capture(*exceptions)
+      begin
+        yield
+      rescue *exceptions => ex
+        raise
+      rescue ::Exception => ex
+        new(ex)
       end
     end
 
+    # Create a failure object that will rethrow the given exception
+    # whenever an undefined method is called.
     def initialize(exception)
       @exception = exception
     end
 
+    # Failure objects will respond to #is_a?.
     def is_a?(klass)
       klass == Failure
     end
 
+    # Failure objects may be compared for equality. If the comparison
+    # object is not a matcher, then the exception is re-raised.
     def ==(other)
       if failure_matcher?(other)
         other.matches?(self)
@@ -28,6 +40,8 @@ module Given
       end
     end
 
+    # Failure objects may be compared for in-equality. If the comparison
+    # object is not a matcher, then the exception is re-raised.
     def !=(other)
       if failure_matcher?(other)
         other.does_not_match?(self)
@@ -36,10 +50,12 @@ module Given
       end
     end
 
+    # Most methods will just re-raise the captured exception.
     def method_missing(sym, *args, &block)
       die
     end
 
+    # Report that we respond to a limited number of methods.
     def respond_to?(method_symbol)
       method_symbol == :call ||
         method_symbol == :== ||
@@ -49,14 +65,15 @@ module Given
 
     private
 
+    # Re-raise the captured exception.
     def die
       ::Kernel.raise @exception
     end
 
+    # Is the comparison object a failure matcher?
     def failure_matcher?(other)
-      other.is_a?(::Given::FailureMatcher) ||
-        (defined?(::RSpec) && other.is_a?(::RSpec::Given::HaveFailed::HaveFailedMatcher))
+      other.respond_to?(:matches?) && other.respond_to?(:does_not_match?)
     end
-
   end
+
 end

data/lib/given/minitest/all.rb

@@ -3,6 +3,7 @@ require 'given'
 
 require 'given/minitest/before_extension'
 require 'given/minitest/context_extension'
+require 'given/minitest/failure_must_raise'
 require 'given/minitest/framework'
 require 'given/minitest/configure'
 

data/lib/given/minitest/failure_must_raise.rb

@@ -0,0 +1,13 @@
+module Given
+
+  class Failure
+    # Minitest expectation method. Since Failure inherits from
+    # BasicObject, we need to add this method explicitly.
+    def must_raise(*args)
+      ::Minitest::Spec.current.assert_raises(*args) do
+        die
+      end
+    end
+  end
+
+end

data/lib/given/module_methods.rb

@@ -54,15 +54,31 @@ module Given
     end
   end
 
+  # Methods forwarded to the framework object.
+
   # Fail an example with the given messages.
-  #
-  # This should be the only place we reference the RSpec function.
-  # Everywhere else in rspec-given should be calling this function.
   def self.fail_with(*args)
     Given.framework.fail_with(*args)
   end
 
-  # Error object used by RSpec to indicate a pending example.
+  # Mark the start of a Then assertion evaluation.
+  def self.start_evaluation(*args)
+    Given.framework.start_evaluation(*args)
+  end
+
+  # Were there any explicit framework assertions made during the
+  # execution of the Then block?
+  def self.explicit_assertions?(*args)
+    Given.framework.explicit_assertions?(*args)
+  end
+
+  # Increment the number of assertions made in the framework.
+  def self.count_assertion(*args)
+    Given.framework.count_assertion(*args)
+  end
+
+  # Error object used by the current framework to indicate a pending
+  # example.
   def self.pending_error
     Given.framework.pending_error
   end

data/lib/given/natural_assertion.rb

@@ -1,5 +1,6 @@
 require 'given/module_methods'
 require 'given/evaluator'
+require 'given/binary_operation'
 
 if Given::NATURAL_ASSERTIONS_SUPPORTED
   require 'ripper'
@@ -36,20 +37,10 @@ module Given
 
     private
 
-    BINARY_EXPLAINATIONS = {
-      :== => "to equal",
-      :!= => "to not equal",
-      :<  => "to be less than",
-      :<= => "to be less or equal to",
-      :>  => "to be greater than",
-      :>= => "to be greater or equal to",
-      :=~ => "to match",
-      :!~ => "to not match",
-    }
-
     def explain_failure
-      if assertion_sexp.first == :binary && msg = BINARY_EXPLAINATIONS[assertion_sexp[2]]
-        @output << explain_expected("expected", assertion_sexp[1], msg, assertion_sexp[3])
+      binary = BinaryOperation.parse(assertion_sexp)
+      if binary && binary.explain
+        @output << explain_expected("expected", binary.left, binary.explain, binary.right)
       end
     end
 
@@ -79,7 +70,7 @@ module Given
     end
 
     def set_file_and_line(block)
-      @code_file, @code_line = eval "[__FILE__, __LINE__]", block.binding
+      @code_file, @code_line = @evaluator.location
       @code_line = @code_line.to_i
     end
 
@@ -97,10 +88,20 @@ module Given
     end
 
     def then_block?(sexp)
-      delve(sexp,0) == :program &&
-        delve(sexp,1,0) == :stmts_add &&
-        delve(sexp,1,2,0) == :method_add_block &&
-        (delve(sexp,1,2,2,0) == :brace_block || delve(sexp,1,2,2,0) == :do_block)
+      program_sexp?(sexp) && method_with_block?(sexp) && has_block_sexp?(sexp)
+    end
+
+    def program_sexp?(sexp)
+      delve(sexp,0) == :program
+    end
+
+    def method_with_block?(sexp)
+      delve(sexp,1,0) == :stmts_add &&
+        delve(sexp,1,2,0) == :method_add_block
+    end
+
+    def has_block_sexp?(sexp)
+      delve(sexp,1,2,2,0) == :brace_block || delve(sexp,1,2,2,0) == :do_block
     end
 
     def extract_first_statement(block_sexp)

data/lib/given/rspec/all.rb

@@ -8,7 +8,7 @@ end
 
 if Given::NATURAL_ASSERTIONS_SUPPORTED
   require 'given/rspec/monkey'
-  raise "Unsupported version of RSpec (unable to detect assertions)" unless RSpec::Given::MONKEY
+  raise "Unsupported version of RSpec (#{RSpec::Version::STRING}), unable to detect assertions" unless RSpec::Given::MONKEY
 end
 
 require 'given/rspec/have_failed'

data/lib/given/rspec/monkey.rb

@@ -1,4 +1,5 @@
 require 'rspec'
+require 'rspec/expectations'
 require 'given/module_methods'
 
 # Monkey patch RSpec to detect matchers used in expectations.

data/lib/given/version.rb

@@ -4,8 +4,6 @@ module Given
     VERSION_MAJOR = 3,
     VERSION_MINOR = 0,
     VERSION_BUILD = 0,
-    BETA = 'beta',
-    BETA_NUMBER = 4,
   ]
   VERSION = VERSION_NUMBERS.join(".")
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: given_core
 version: !ruby/object:Gem::Version
-  version: 3.0.0.beta.4
+  version: 3.0.0
 platform: ruby
 authors:
 - Jim Weirich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-10 00:00:00.000000000 Z
+date: 2013-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorcerer
@@ -37,9 +37,11 @@ files:
 - Gemfile.lock
 - MIT-LICENSE
 - README.md
+- README.old
 - Rakefile
 - TODO
 - lib/given.rb
+- lib/given/binary_operation.rb
 - lib/given/core.rb
 - lib/given/evaluator.rb
 - lib/given/ext/numeric.rb
@@ -54,6 +56,7 @@ files:
 - lib/given/minitest/before_extension.rb
 - lib/given/minitest/configure.rb
 - lib/given/minitest/context_extension.rb
+- lib/given/minitest/failure_must_raise.rb
 - lib/given/minitest/framework.rb
 - lib/given/minitest/new_assertions.rb
 - lib/given/module_methods.rb
@@ -96,9 +99,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: given
 rubygems_version: 2.0.3