Add expose_current_running_example_as config option.

Fixes #963.

lib/rspec/core/configuration.rb

@@ -965,6 +965,39 @@ def warnings
         $VERBOSE
       end
 
+      # Exposes the current running example via the named
+      # helper method. RSpec 2.x exposed this via `example`,
+      # but in RSpec 3.0, the example is instead exposed via
+      # an arg yielded to `it`, `before`, `let`, etc. However,
+      # some extension gems (such as Capybara) depend on the
+      # RSpec 2.x's `example` method, so this config option
+      # can be used to maintain compatibility.
+      #
+      # @param method_name [Symbol] the name of the helper method
+      #
+      # @example
+      #
+      #   RSpec.configure do |rspec|
+      #     rspec.expose_current_running_example_as :example
+      #   end
+      #
+      #   describe MyClass do
+      #     before do
+      #       # `example` can be used here because of the above config.
+      #       do_something if example.metadata[:type] == "foo"
+      #     end
+      #   end
+      def expose_current_running_example_as(method_name)
+        ExposeCurrentExample.module_eval do
+          extend RSpec::SharedContext
+          let(method_name) { |ex| ex }
+        end
+
+        include ExposeCurrentExample
+      end
+
+      module ExposeCurrentExample; end
+
     private
 
       def get_files_to_run(paths)

spec/rspec/core/configuration_spec.rb

@@ -1436,5 +1436,20 @@ def strategy.order(list)
       end
     end
 
+    describe "#expose_current_running_example_as" do
+      it 'exposes the current example via the named method' do
+        RSpec.configuration.expose_current_running_example_as :the_example
+
+        value = nil
+
+        ExampleGroup.describe "Group" do
+          it("works") { value = the_example }
+        end.run
+
+        expect(value).to be_an(RSpec::Core::Example)
+        expect(value.description).to eq("works")
+      end
+    end
+
   end
 end