rspec-given 2.3.0 → 2.3.1.beta.1

data/README.md

@@ -1,6 +1,6 @@
 # rspec-given
 
-Covering rspec-given, version 2.3.0.
+Covering rspec-given, version 2.3.1.beta.1.
 
 rspec-given is an RSpec extension to allow Given/When/Then notation in
 RSpec specifications.  It is a natural extension of the experimental
@@ -17,7 +17,7 @@ RSpec specifications.
 
 ## Status
 
-_rspec-given_ is ready for production use.
+rspec-given is ready for production use.
 
 ## Example
 
@@ -118,7 +118,7 @@ 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 out
+will inherit the preconditions from the enclosing context, with outer
 preconditions running before inner preconditions.
 
 #### Given examples:
@@ -127,8 +127,8 @@ preconditions running before inner preconditions.
     Given(:stack) { Stack.new }
 ```
 
-The block for the given clause is lazily run if 'stack' is ever
-referenced in the test and the value of the block is bound to 'stack'.
+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.
@@ -259,7 +259,7 @@ be empty. If it is not empty, the test will fail.
 
 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_ an multiple _And_ clauses in an
+_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
@@ -267,30 +267,30 @@ expensive.
 
 Some things to keep in mind about _And_ clauses:
 
-1. 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.
+* 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.
 
-1. The code in the _And_ clause is run immediately after the first
-   (executed) _Then_ of an example group.
+* The code in the _And_ clause is run immediately after the first
+  (executed) _Then_ of an example group.
 
-1. And assertion failures in a _Then_ clause or a _And_ clause will
-   cause all the subsequent _And_ clauses to be skipped.
+* An assertion failure in a _Then_ clause or an _And_ clause will
+  cause all the subsequent _And_ clauses to be skipped.
 
-1. 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).
+* 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).
 
-1. 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).
+* 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_
-clause will speed up the spec. Otherwise it is probably better to
+clauses will speed up the spec. Otherwise it is probably better to
 stick with _Then_ clauses.
 
 #### Then/And examples:
@@ -326,18 +326,19 @@ used in contexts that define that accessor.
 
 Notes:
 
-1. Since Invariants do not form their own RSpec example, they are not
-   represented in the RSpec formatted output (e.g. the '--format html'
-   option).
+* 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 _Given_ clauses will be run in the order that they are
+* 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_.
+  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.
@@ -347,21 +348,22 @@ be true:
 
 * _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.
+  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
-a not strongly specified. Hoisting a _When_ clause out of an inner
-scope to an outer scope may change the ordering of when the _Given_
-clause runs in relation to a _before_ block (the hoisting will cause
-the givens to possibly run earlier).  Because of this, do not split
-order dependent code between _Given_ clauses and _before_ blocks.
+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
 
-**NOTE:** <em>Natural assertions are an experimental feature of
-RSpec/Given. They are currently disabled by default. They can be
+**NOTE:** <em>Natural assertions are currently an experimental feature
+of RSpec/Given. They are currently disabled by default, but can be
 enabled by a simple configuration option (see "use_natural_assertions"
 below).</em>
 
@@ -380,6 +382,10 @@ natural assertions:
 Natural assertions must be enabled, either globally or on a per
 context basis, to be recognized.
 
+Here's a heads up: If you use natural assertions, but fail to enable
+them, 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
@@ -418,26 +424,26 @@ 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 expressions will give additional information (e.g. "expected:
+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 (=~,
 !~).
 
 ### Caveats on Natural Assertions
 
-Keep the following in mind when using 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 breakdown the values for each part).
+  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
+  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
+  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
@@ -458,8 +464,8 @@ 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 block, then just
-assert what you need about the result from the when block. Something
+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
@@ -510,7 +516,7 @@ 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 hepful, it is
+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
@@ -520,7 +526,7 @@ exactly equal, therefore it is useful to assert that two floating
 point numbers are nearly equal.
 
 For example, the following asserts that the square root of 10 is about
-3.1523 with an accuracy of 0.1 percent.
+3.1523 with an accuracy of 1 percent.
 
 ```ruby
     Then { Math.sqrt(10) == about(3.1623).percent(1) }
@@ -562,7 +568,8 @@ For example, the following two Then clauses are equivalent:
 
 ### Processing Natural Assertions
 
-When natural assertions are enabled, they are only used if:
+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).
@@ -588,8 +595,8 @@ Conover](http://rubygems.org/profiles/sconoversf).
 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 are chosen,
-RSpec/Given will automatically add addition source code information to
+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:

data/Rakefile

@@ -93,6 +93,13 @@ task :verify_rspec2 do
   end
 end
 
+task :load_check do
+  SRC_FILES = FileList['lib/rspec/given/*.rb'].exclude(/rspec1/)
+  SRC_FILES.each do |fn|
+    sh %{ruby -Ilib -e 'load "#{fn}"'}
+  end
+end
+
 # Formatting the README ----------------------------------------------
 
 directory 'html'

data/examples/example_helper.rb

@@ -1,3 +1,3 @@
 $LOAD_PATH << './examples/stack'
 
-require 'rspec/given'
+require 'spec_helper'

data/examples/integration/then_spec.rb

@@ -3,7 +3,7 @@ require 'example_helper'
 
 describe "Then" do
   context "empty thens with natural assertions" do
-    use_natural_assertions
+    use_natural_assertions_if_supported
     Then { }
   end
 end

data/lib/rspec/given/extensions.rb

@@ -206,6 +206,8 @@ module RSpec
             begin
               _rg_establish_givens
               instance_eval(&block)
+            rescue RSpec::Core::Pending::PendingDeclaredInExample => ex
+              raise
             rescue Exception => ex
               Failure.new(ex)
             end
@@ -252,6 +254,7 @@ module RSpec
       end
 
       def use_natural_assertions(enabled=true)
+        RSpec::Given.ok_to_use_natural_assertions(enabled)
         _rgc_context_info[:natural_assertions_enabled] = enabled
       end
     end

data/lib/rspec/given/have_failed.rb

@@ -1,3 +1,5 @@
+require 'rspec'
+
 module RSpec
   module Given
     module HaveFailed

data/lib/rspec/given/module_methods.rb

@@ -1,5 +1,7 @@
 module RSpec
   module Given
+    NATURAL_ASSERTIONS_SUPPORTED = ! defined?(JRUBY_VERSION)
+
     def self.matcher_called
       @matcher_called
     end
@@ -22,9 +24,16 @@ module RSpec
     end
 
     def self.use_natural_assertions(enabled=true)
+      ok_to_use_natural_assertions(enabled)
       @natural_assertions_enabled = enabled
     end
 
+    def self.ok_to_use_natural_assertions(enabled)
+      if enabled && ! NATURAL_ASSERTIONS_SUPPORTED
+        fail ArgumentError, "Natural Assertions are disabled for JRuby"
+      end
+    end
+
     def self.natural_assertions_enabled?
       @natural_assertions_enabled
     end

data/lib/rspec/given/monkey.rb

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

data/lib/rspec/given/natural_assertion.rb

@@ -1,6 +1,11 @@
-require 'ripper'
-require 'sorcerer'
-require 'rspec/given/monkey'
+require 'rspec'
+require 'rspec/given/module_methods'
+
+if RSpec::Given::NATURAL_ASSERTIONS_SUPPORTED
+  require 'ripper'
+  require 'sorcerer'
+  require 'rspec/given/monkey'
+end
 
 module RSpec
   module Given
@@ -160,7 +165,7 @@ module RSpec
         width = suggest_width(pairs)
         pairs.each do |x, v|
           fmt = (v.size > WRAP_WIDTH) ?
-            "  %-#{width+2}s\n  #{' '*(width+2)} <- %s\n" :
+          "  %-#{width+2}s\n  #{' '*(width+2)} <- %s\n" :
             "  %-#{width+2}s <- %s\n"
           @output << sprintf(fmt, v, x)
         end

data/lib/rspec/given/rspec1_given.rb

@@ -2,7 +2,8 @@ require 'rspec/given/version'
 require 'rspec/given/extensions'
 
 class Spec::ExampleGroup
-  extend RSpec::Given::Extensions
+  extend RSpec::Given::ClassExtensions
+  include RSpec::Given::InstanceExtensions
 
   class << self
     alias Then specify

data/lib/rspec/given/version.rb

@@ -3,7 +3,8 @@ module RSpec
     VERSION_NUMBERS = [
       VERSION_MAJOR = 2,
       VERSION_MINOR = 3,
-      VERSION_BUILD = 0,
+      VERSION_BUILD = 1,
+      'beta', 1
     ]
     VERSION = VERSION_NUMBERS.join(".")
   end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: rspec-given
 version: !ruby/object:Gem::Version
-  version: 2.3.0
-  prerelease: 
+  version: 2.3.1.beta.1
+  prerelease: 6
 platform: ruby
 authors:
 - Jim Weirich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-18 00:00:00.000000000 Z
+date: 2013-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -27,22 +27,6 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '2.11'
-- !ruby/object:Gem::Dependency
-  name: sorcerer
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 0.3.7
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 0.3.7
 - !ruby/object:Gem::Dependency
   name: bluecloth
   requirement: !ruby/object:Gem::Requirement
@@ -154,9 +138,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: given
 rubygems_version: 1.8.24