transpec 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2402b33bb816bb8834d369cd49ea5b93199f0c7f
-  data.tar.gz: 3fc7140d2ebbf711de884459b1a8d424ce073a1f
+  metadata.gz: d068540b9a2d9d54a04b4314bd3c5156c423ba4f
+  data.tar.gz: cbbb7e6061a8d5cf4ee52054e1e7bb1da4ea8a08
 SHA512:
-  metadata.gz: e023997e0b62507e833df7fe92a7fad689c2aa6fc601378df904e54d66d8122ea97af22eec4ca8c0c901aa043c7717221188dba3871828e0822e104b4d6e93f2
-  data.tar.gz: 1c2c697e5f2d143be79ecc6d8718e488466eb3f53c3d9629fd94c447529ab5c0c1423f4333c28b6af07f4a657aac48b37d291a25e69dde1b01b51ad0699f6ca9
+  metadata.gz: bb03eeaa658581eb344bafff2a1bd0e38931bdd804b76be305fab9154efdb858306f8a5db2c7292210289ba5dfe74af02797a9d49896aab229c46af6ae2124a7
+  data.tar.gz: e7c2dfa4ba98e945c3d0d9363a1151d68eba25ea8c869191212b8dbc6cca7b04fd64b51af38c8b0f3855288b798f74c06719d234ab7a1723acdbed1421533802

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Development
 
+## v2.2.0
+
+* Add descriptive comments to auto-added configurations in `RSpec.configure`.
+* Deprecate `--no-parentheses-matcher-arg` option in favor of `--no-parens-matcher-arg`.
+* Remove consecutive white spaces between `its` and the block.
+
 ## v2.1.0
 
 * Disable invalid conversion of `expect(model).to have(n).errors_on(:attr)`. ([#62](https://github.com/yujinakayama/transpec/issues/62))

data/README.md

@@ -8,17 +8,20 @@
 
 **Transpec** is a tool for converting your specs to the latest [RSpec](http://rspec.info/) syntax with static and dynamic code analysis.
 
-This aims to facilitate a smooth transition to RSpec 3, and it's now ready for RSpec 2.99 and 3.0 beta!
+With Transpec you can upgrade your RSpec 2 specs to RSpec 3 in no time.
+It supports [conversions](#supported-conversions) for almost all of the RSpec 3 changes – not only the `expect` syntax.
+Also, you can use it on your RSpec 2 project even if you're not going to upgrade it to RSpec 3 for now.
 
-See the following pages for the new RSpec syntax and the plan for RSpec 3:
+Check out the following pages for the new RSpec syntax and the changes in RSpec 3:
 
 * [Myron Marston » RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax)
 * [RSpec's new message expectation syntax - Tea is awesome.](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/)
-* [Myron Marston » The Plan for RSpec 3](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3)
+* [Myron Marston » Notable Changes in RSpec 3](http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3)
 
-Transpec now supports conversions for almost all of the RSpec 3 changes,
-but the changes are not fixed and may vary in the future.
-So it's recommended to follow updates of both RSpec and Transpec.
+If you are going to use Transpec in the upgrade process to RSpec 3,
+read the RSpec official guide:
+
+* https://relishapp.com/rspec/docs/upgrade
 
 ## Examples
 
@@ -193,13 +196,6 @@ $ transpec --keep its --convert example_group
 
 See [`-k/--keep`](#-k--keep) and [`-v/--convert`](#-v--convert) for more details.
 
-## Upgrade Process to RSpec 3 beta
-
-If you are going to use Transpec in the upgrade process to RSpec 3 beta,
-read this article by [Myron Marston](https://github.com/myronmarston), who is the lead maintainer of RSpec:
-
-* [Myron Marston » RSpec 2.99 and 3.0 betas have been released!](http://myronmars.to/n/dev-blog/2013/11/rspec-2-99-and-3-0-betas-have-been-released)
-
 ## Options
 
 Though Transpec ships with sensible defaults that essentially conform to the RSpec 3 defaults,
@@ -329,7 +325,7 @@ Note that this is not same as `--keep deprecated` since this configures `yield_r
 
 See [Supported Conversions - `any_instance` implementation blocks](#any_instance-implementation-blocks) for more details.
 
-### `-p/--no-parentheses-matcher-arg`
+### `-p/--no-parens-matcher-arg`
 
 Suppress parenthesizing arguments of matchers when converting
 `should` with operator matcher to `expect` with non-operator matcher
@@ -358,7 +354,7 @@ describe 'converted spec' do
   end
 end
 
-describe 'converted spec with -p/--no-parentheses-matcher-arg option' do
+describe 'converted spec with -p/--no-parens-matcher-arg option' do
   it 'is an example' do
     expect(1).to eq 1
     expect(2).to be > 1
@@ -483,7 +479,7 @@ The one-liner (implicit receiver) `should`:
 * [Current example object](#current-example-object)
 * [Custom matcher DSL](#custom-matcher-dsl)
 * [Implicit spec types in rspec-rails](#implicit-spec-types-in-rspec-rails)
-* [Example groups](#example-groups)
+* [Monkey-patched example groups](#monkey-patched-example-groups)
 * [Hook scope aliases](#hook-scope-aliases)
 
 ### Standard expectations
@@ -509,7 +505,7 @@ expect(obj).to_not matcher # with `--negative-form to_not`
 
 ### One-liner expectations
 
-**This conversion is available only if your project's RSpec is `2.99.0.beta2` or later.**
+This conversion is available only if your project's RSpec is **2.99.0.beta2 or later**.
 
 Targets:
 
@@ -566,7 +562,7 @@ This conversion is combined with the conversion of [standard expectations](#stan
 
 ### Boolean matchers
 
-**This conversion is available only if your project's RSpec is `2.99.0.beta1` or later.**
+This conversion is available only if your project's RSpec is **2.99.0.beta1 or later**.
 
 Targets:
 
@@ -622,7 +618,7 @@ expect(1.0 / 3.0).to be_within(0.001).of(0.333)
 
 ### `have(n).items` matcher
 
-**This conversion will be disabled automatically if `rspec-collection_matchers` is loaded in your spec.**
+This conversion will be **disabled automatically if `rspec-collection_matchers` is loaded** in your spec.
 
 Targets:
 
@@ -696,7 +692,7 @@ So using rspec-collection_matchers gem is recommended for now.
 
 ### One-liner expectations with `have(n).items` matcher
 
-**This conversion will be disabled automatically if `rspec-collection_matchers` is loaded in your spec.**
+This conversion will be **disabled automatically if `rspec-collection_matchers` is loaded** in your spec.
 
 Targets:
 
@@ -746,7 +742,7 @@ expect { do_something }.to raise_error
 
 ### Expectations on attribute of subject with `its`
 
-**This conversion will be disabled automatically if `rspec-its` is loaded in your spec.**
+This conversion will be **disabled automatically if `rspec-its` is loaded** in your spec.
 
 Targets:
 
@@ -791,7 +787,9 @@ If you choose to do so, disable this conversion by either:
 * Specify `--keep its` option manually.
 * Require `rspec-its` in your spec so that Transpec automatically disables this conversion.
 
----
+Note that this conversion is a sort of first-aid
+and ideally the expectations should be rewritten to be more expressive by yourself.
+Read [this post](https://gist.github.com/myronmarston/4503509) for the rationale.
 
 * This conversion can be disabled by: `--keep its`
 * Deprecation: deprecated since RSpec 2.99, removed in RSpec 3.0
@@ -1008,7 +1006,7 @@ allow(obj).to receive(:message)
 
 ### `any_instance` implementation blocks
 
-**This conversion is available only if your project's RSpec is `>= 2.99.0.beta1` and `< 3.0.0.beta1`.**
+This conversion is available only if your project's RSpec is **`>= 2.99.0.beta1` and `< 3.0.0.beta1`**.
 
 Targets:
 
@@ -1029,6 +1027,13 @@ Will be converted to:
 ```ruby
 RSpec.configure do |rspec|
   rspec.mock_with :rspec do |mocks|
+    # In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
+    # instance as the first block argument to allow the implementation block to use
+    # the state of the receiver.
+    # In RSpec 2.99, to maintain compatibility with RSpec 3 you need to either set
+    # this config option to `false` OR set this to `true` and update your
+    # `any_instance` implementation blocks to account for the first block argument
+    # being the receiving instance.
     mocks.yield_receiver_to_any_instance_implementation_blocks = true
   end
 end
@@ -1039,10 +1044,20 @@ describe 'example' do
     allow_any_instance_of(Klass).to receive(:message) { |instance, arg| puts arg }
   end
 end
+```
+
+Or with `--no-yield-any-instance` option they will be converted to:
 
-# With `--no-yield-any-instance`
+```
 RSpec.configure do |rspec|
   rspec.mock_with :rspec do |mocks|
+    # In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
+    # instance as the first block argument to allow the implementation block to use
+    # the state of the receiver.
+    # In RSpec 2.99, to maintain compatibility with RSpec 3 you need to either set
+    # this config option to `false` OR set this to `true` and update your
+    # `any_instance` implementation blocks to account for the first block argument
+    # being the receiving instance.
     mocks.yield_receiver_to_any_instance_implementation_blocks = false
   end
 end
@@ -1055,25 +1070,6 @@ describe 'example' do
 end
 ```
 
-Here's an excerpt from [the warning](https://github.com/rspec/rspec-mocks/blob/aab8dc9/lib/rspec/mocks/message_expectation.rb#L478-L491) for `any_instance` implementation blocks in RSpec 2.99:
-
-> In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
-> instance as the first block argument to allow the implementation block to use
-> the state of the receiver.  To maintain compatibility with RSpec 3 you need to
-> either set rspec-mocks' `yield_receiver_to_any_instance_implementation_blocks`
-> config option to `false` OR set it to `true` and update your `any_instance`
-> implementation blocks to account for the first block argument being the receiving instance.
->
-> To set the config option, use a snippet like:
->
-> ```ruby
-> RSpec.configure do |rspec|
->   rspec.mock_with :rspec do |mocks|
->     mocks.yield_receiver_to_any_instance_implementation_blocks = false
->   end
-> end
-> ```
-
 * This conversion can be disabled by: `--keep deprecated`
 * Deprecation: deprecated since RSpec 2.99
 * See also: [Mocks: `any_instance` block implementations will yield the receiver](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3#mocks__block_implementations_will_yield_the_receiver)
@@ -1099,7 +1095,7 @@ double('something')
 
 ### Pending examples
 
-**This conversion is available only if your project's RSpec is `>= 2.99.0.beta1` and `< 3.0.0.beta1`.**
+This conversion is available only if your project's RSpec is **`>= 2.99.0.beta1` and `< 3.0.0.beta1`**.
 
 Targets:
 
@@ -1168,7 +1164,7 @@ Here's an excerpt from [the warning](https://github.com/rspec/rspec-core/blob/v2
 
 ### Current example object
 
-**This conversion is available only if your project's RSpec is `2.99.0.beta1` or later.**
+This conversion is available only if your project's RSpec is **2.99.0.beta1 or later**.
 
 Targets:
 
@@ -1226,7 +1222,7 @@ Here's an excerpt from [the warning](https://github.com/rspec/rspec-core/blob/7d
 
 ### Custom matcher DSL
 
-**This conversion is available only if your project's RSpec is `3.0.0.beta2` or later.**
+This conversion is available only if your project's RSpec is **3.0.0.beta2 or later**.
 
 Targets:
 
@@ -1256,7 +1252,7 @@ end
 
 ### Implicit spec types in rspec-rails
 
-**This conversion is available only if `rspec-rails` is loaded in your spec and your project's RSpec is `2.99.0.rc1` or later.**
+This conversion is **available only if `rspec-rails` is loaded** in your spec and your project's RSpec is **2.99.0.rc1 or later**.
 
 Targets:
 
@@ -1277,9 +1273,21 @@ end
 
 describe SomeModel, :type => :model do
 end
+```
 
-# With `--no-explicit-spec-type`
+Or with `--no-explicit-spec-type` option they will be converted to:
+
+```
 RSpec.configure do |rspec|
+  # rspec-rails 3 will no longer automatically infer an example group's spec type
+  # from the file location. You can explicitly opt-in to the feature using this
+  # config option.
+  # To explicitly tag specs without using automatic inference, set the `:type`
+  # metadata manually:
+  #
+  #     describe ThingsController, :type => :controller do
+  #       # Equivalent to being in spec/controllers
+  #     end
   rspec.infer_spec_type_from_file_location!
 end
 
@@ -1287,25 +1295,13 @@ describe SomeModel do
 end
 ```
 
-Here's an excerpt from [the warning](https://github.com/rspec/rspec-rails/blob/ab6313b/lib/rspec/rails/infer_type_configuration.rb#L13-L22) in RSpec 2.99:
-
-> rspec-rails 3 will no longer automatically infer an example group's spec type from the file location. You can explicitly opt-in to this feature using this snippet:
->
-> ```ruby
-> RSpec.configure do |config|
->   config.infer_spec_type_from_file_location!
-> end
-> ```
->
-> If you wish to manually label spec types via metadata you can safely ignore this warning and continue upgrading to RSpec 3 without addressing it.
-
 * This conversion can be disabled by: `--keep deprecated`
 * Deprecation: deprecated since RSpec 2.99, removed in RSpec 3.0
 * See also: [Consider making example group mixins more explicit · rspec/rspec-rails](https://github.com/rspec/rspec-rails/issues/662)
 
-### Example groups
+### Monkey-patched example groups
 
-**This conversion is disabled by default and available only if your project's RSpec is `3.0.0.beta2` or later.**
+This conversion is **disabled by default** and available only if your project's RSpec is **3.0.0.beta2 or later**.
 
 Targets:
 
@@ -1326,6 +1322,13 @@ Will be converted to:
 
 ```ruby
 RSpec.configure do |rspec|
+  # Setting this config option `false` removes rspec-core's monkey patching of the
+  # top level methods like `describe`, `shared_examples_for` and `shared_context`
+  # on `main` and `Module`. The methods are always available through the `RSpec`
+  # module like `RSpec.describe` regardless of this setting.
+  # For backwards compatibility this defaults to `true`.
+  #
+  # https://relishapp.com/rspec/rspec-core/v/3-0/docs/configuration/global-namespace-dsl
   rspec.expose_dsl_globally = false
 end
 
@@ -1344,7 +1347,7 @@ end
 
 ### Hook scope aliases
 
-**This conversion is disabled by default and available only if your project's RSpec is `3.0.0.beta2` or later.**
+This conversion is **disabled by default** and available only if your project's RSpec is **3.0.0.beta2 or later**.
 
 Targets:
 

data/README.md.erb

@@ -8,17 +8,20 @@
 
 **Transpec** is a tool for converting your specs to the latest [RSpec](http://rspec.info/) syntax with static and dynamic code analysis.
 
-This aims to facilitate a smooth transition to RSpec 3, and it's now ready for RSpec 2.99 and 3.0 beta!
+With Transpec you can upgrade your RSpec 2 specs to RSpec 3 in no time.
+It supports [conversions](#supported-conversions) for almost all of the RSpec 3 changes – not only the `expect` syntax.
+Also, you can use it on your RSpec 2 project even if you're not going to upgrade it to RSpec 3 for now.
 
-See the following pages for the new RSpec syntax and the plan for RSpec 3:
+Check out the following pages for the new RSpec syntax and the changes in RSpec 3:
 
 * [Myron Marston » RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax)
 * [RSpec's new message expectation syntax - Tea is awesome.](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/)
-* [Myron Marston » The Plan for RSpec 3](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3)
+* [Myron Marston » Notable Changes in RSpec 3](http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3)
 
-Transpec now supports conversions for almost all of the RSpec 3 changes,
-but the changes are not fixed and may vary in the future.
-So it's recommended to follow updates of both RSpec and Transpec.
+If you are going to use Transpec in the upgrade process to RSpec 3,
+read the RSpec official guide:
+
+* https://relishapp.com/rspec/docs/upgrade
 
 ## Examples
 
@@ -167,13 +170,6 @@ $ transpec --keep its --convert example_group
 
 See [`-k/--keep`](#-k--keep) and [`-v/--convert`](#-v--convert) for more details.
 
-## Upgrade Process to RSpec 3 beta
-
-If you are going to use Transpec in the upgrade process to RSpec 3 beta,
-read this article by [Myron Marston](https://github.com/myronmarston), who is the lead maintainer of RSpec:
-
-* [Myron Marston » RSpec 2.99 and 3.0 betas have been released!](http://myronmars.to/n/dev-blog/2013/11/rspec-2-99-and-3-0-betas-have-been-released)
-
 ## Options
 
 Though Transpec ships with sensible defaults that essentially conform to the RSpec 3 defaults,
@@ -317,7 +313,7 @@ Note that this is not same as `--keep deprecated` since this configures `yield_r
 
 See [Supported Conversions - `any_instance` implementation blocks](#any_instance-implementation-blocks) for more details.
 
-### `-p/--no-parentheses-matcher-arg`
+### `-p/--no-parens-matcher-arg`
 
 Suppress parenthesizing arguments of matchers when converting
 `should` with operator matcher to `expect` with non-operator matcher
@@ -346,7 +342,7 @@ END
 convert(example, cli: ['-p'])
   .gsub(
     'original spec',
-    'converted spec with -p/--no-parentheses-matcher-arg option'
+    'converted spec with -p/--no-parens-matcher-arg option'
   )
   .gsub(/^.+\{ key: value \}/) do |match|
     "    # With non-operator method, the parentheses are always required\n" +
@@ -481,7 +477,7 @@ Will be converted to:
 
 ### One-liner expectations
 
-**This conversion is available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.oneliner_is_expected_available_version %>` or later.**
+This conversion is available only if your project's RSpec is **<%= rspec_version = Transpec::RSpecVersion.oneliner_is_expected_available_version %> or later**.
 
 Targets:
 
@@ -546,7 +542,7 @@ This conversion is combined with the conversion of [standard expectations](#stan
 
 ### Boolean matchers
 
-**This conversion is available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.be_truthy_available_version %>` or later.**
+This conversion is available only if your project's RSpec is **<%= rspec_version = Transpec::RSpecVersion.be_truthy_available_version %> or later**.
 
 Targets:
 
@@ -607,7 +603,7 @@ Will be converted to:
 
 ### `have(n).items` matcher
 
-**This conversion will be disabled automatically if `rspec-collection_matchers` is loaded in your spec.**
+This conversion will be **disabled automatically if `rspec-collection_matchers` is loaded** in your spec.
 
 Targets:
 
@@ -751,7 +747,7 @@ So using rspec-collection_matchers gem is recommended for now.
 
 ### One-liner expectations with `have(n).items` matcher
 
-**This conversion will be disabled automatically if `rspec-collection_matchers` is loaded in your spec.**
+This conversion will be **disabled automatically if `rspec-collection_matchers` is loaded** in your spec.
 
 Targets:
 
@@ -819,7 +815,7 @@ Will be converted to:
 
 ### Expectations on attribute of subject with `its`
 
-**This conversion will be disabled automatically if `rspec-its` is loaded in your spec.**
+This conversion will be **disabled automatically if `rspec-its` is loaded** in your spec.
 
 Targets:
 
@@ -848,7 +844,9 @@ If you choose to do so, disable this conversion by either:
 * Specify `--keep its` option manually.
 * Require `rspec-its` in your spec so that Transpec automatically disables this conversion.
 
----
+Note that this conversion is a sort of first-aid
+and ideally the expectations should be rewritten to be more expressive by yourself.
+Read [this post](https://gist.github.com/myronmarston/4503509) for the rationale.
 
 * This conversion can be disabled by: `--keep its`
 * Deprecation: deprecated since RSpec 2.99, removed in RSpec 3.0
@@ -1110,7 +1108,7 @@ Will be converted to:
 
 ### `any_instance` implementation blocks
 
-**This conversion is available only if your project's RSpec is `>= <%= Transpec::RSpecVersion::RSPEC_2_99 %>` and `< <%= Transpec::RSpecVersion::RSPEC_3_0 %>`.**
+This conversion is available only if your project's RSpec is **`>= <%= Transpec::RSpecVersion::RSPEC_2_99 %>` and `< <%= Transpec::RSpecVersion::RSPEC_3_0 %>`**.
 
 Targets:
 
@@ -1135,29 +1133,13 @@ Will be converted to:
 ```ruby
 <% rspec_version = Transpec::RSpecVersion.yielding_receiver_to_any_instance_implementation_block_available_version -%>
 <%= convert(example, rspec_version: rspec_version) -%>
-
-# With `--no-yield-any-instance`
-<%= convert(example, cli: ['--no-yield-any-instance'], rspec_version: rspec_version) -%>
 ```
 
-Here's an excerpt from [the warning](https://github.com/rspec/rspec-mocks/blob/aab8dc9/lib/rspec/mocks/message_expectation.rb#L478-L491) for `any_instance` implementation blocks in RSpec 2.99:
+Or with `--no-yield-any-instance` option they will be converted to:
 
-> In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
-> instance as the first block argument to allow the implementation block to use
-> the state of the receiver.  To maintain compatibility with RSpec 3 you need to
-> either set rspec-mocks' `yield_receiver_to_any_instance_implementation_blocks`
-> config option to `false` OR set it to `true` and update your `any_instance`
-> implementation blocks to account for the first block argument being the receiving instance.
->
-> To set the config option, use a snippet like:
->
-> ```ruby
-> RSpec.configure do |rspec|
->   rspec.mock_with :rspec do |mocks|
->     mocks.yield_receiver_to_any_instance_implementation_blocks = false
->   end
-> end
-> ```
+```
+<%= convert(example, cli: ['--no-yield-any-instance'], rspec_version: rspec_version) -%>
+```
 
 * This conversion can be disabled by: `--keep deprecated`
 * Deprecation: deprecated since RSpec 2.99
@@ -1188,7 +1170,7 @@ Will be converted to:
 
 ### Pending examples
 
-**This conversion is available only if your project's RSpec is `>= <%= Transpec::RSpecVersion::RSPEC_2_99 %>` and `< <%= Transpec::RSpecVersion::RSPEC_3_0 %>`.**
+This conversion is available only if your project's RSpec is **`>= <%= Transpec::RSpecVersion::RSPEC_2_99 %>` and `< <%= Transpec::RSpecVersion::RSPEC_3_0 %>`**.
 
 Targets:
 
@@ -1246,7 +1228,7 @@ Here's an excerpt from [the warning](https://github.com/rspec/rspec-core/blob/v2
 
 ### Current example object
 
-**This conversion is available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.yielded_example_available_version %>` or later.**
+This conversion is available only if your project's RSpec is **<%= rspec_version = Transpec::RSpecVersion.yielded_example_available_version %> or later**.
 
 Targets:
 
@@ -1296,7 +1278,7 @@ Here's an excerpt from [the warning](https://github.com/rspec/rspec-core/blob/7d
 
 ### Custom matcher DSL
 
-**This conversion is available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.non_should_matcher_protocol_available_version %>` or later.**
+This conversion is available only if your project's RSpec is **<%= rspec_version = Transpec::RSpecVersion.non_should_matcher_protocol_available_version %> or later**.
 
 Targets:
 
@@ -1325,7 +1307,7 @@ Will be converted to:
 
 ### Implicit spec types in rspec-rails
 
-**This conversion is available only if `rspec-rails` is loaded in your spec and your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.implicit_spec_type_disablement_available_version %>` or later.**
+This conversion is **available only if `rspec-rails` is loaded** in your spec and your project's RSpec is **<%= rspec_version = Transpec::RSpecVersion.implicit_spec_type_disablement_available_version %> or later**.
 
 Targets:
 
@@ -1346,30 +1328,21 @@ Will be converted to:
 
 ```ruby
 <%= convert(example, rspec_version: rspec_version, path: 'spec/models/some_model_spec.rb') -%>
-
-# With `--no-explicit-spec-type`
-<%= convert(example, rspec_version: rspec_version, path: 'spec/models/some_model_spec.rb', cli: ['--no-explicit-spec-type']) -%>
 ```
 
-Here's an excerpt from [the warning](https://github.com/rspec/rspec-rails/blob/ab6313b/lib/rspec/rails/infer_type_configuration.rb#L13-L22) in RSpec 2.99:
+Or with `--no-explicit-spec-type` option they will be converted to:
 
-> rspec-rails 3 will no longer automatically infer an example group's spec type from the file location. You can explicitly opt-in to this feature using this snippet:
->
-> ```ruby
-> RSpec.configure do |config|
->   config.infer_spec_type_from_file_location!
-> end
-> ```
->
-> If you wish to manually label spec types via metadata you can safely ignore this warning and continue upgrading to RSpec 3 without addressing it.
+```
+<%= convert(example, rspec_version: rspec_version, path: 'spec/models/some_model_spec.rb', cli: ['--no-explicit-spec-type']) -%>
+```
 
 * This conversion can be disabled by: `--keep deprecated`
 * Deprecation: deprecated since RSpec 2.99, removed in RSpec 3.0
 * See also: [Consider making example group mixins more explicit · rspec/rspec-rails](https://github.com/rspec/rspec-rails/issues/662)
 
-### Example groups
+### Monkey-patched example groups
 
-**This conversion is disabled by default and available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.non_monkey_patch_example_group_available_version %>` or later.**
+This conversion is **disabled by default** and available only if your project's RSpec is **<%= rspec_version = Transpec::RSpecVersion.non_monkey_patch_example_group_available_version %> or later**.
 
 Targets:
 
@@ -1402,7 +1375,7 @@ Will be converted to:
 
 ### Hook scope aliases
 
-**This conversion is disabled by default and available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.hook_scope_alias_available_version %>` or later.**
+This conversion is **disabled by default** and available only if your project's RSpec is **<%= rspec_version = Transpec::RSpecVersion.hook_scope_alias_available_version %> or later**.
 
 Targets:
 

data/lib/transpec/option_parser.rb

@@ -95,7 +95,7 @@ module Transpec
         config.add_explicit_type_metadata_to_example_group = false
       end
 
-      define_option('-p', '--no-parentheses-matcher-arg') do
+      define_option('-p', '--no-parens-matcher-arg') do
         config.parenthesize_matcher_arg = false
       end
 
@@ -207,12 +207,20 @@ module Transpec
     end
 
     def convert_deprecated_options(raw_args)
-      raw_args.dup
+      raw_args.each_with_object([]) do |arg, args|
+        case arg
+        when '--no-parentheses-matcher-arg'
+          deprecate('--no-parentheses-matcher-arg option', '--no-parens-matcher-arg')
+          args << '--no-parens-matcher-arg'
+        else
+          args << arg
+        end
+      end
     end
 
     def deprecate(subject, alternative = nil)
       message =  "DEPRECATION: #{subject} is deprecated."
-      message << " Please use #{alternative} instead." if alternative
+      message << " Use #{alternative} instead." if alternative
       warn message
     end
 

data/lib/transpec/syntax/its.rb

@@ -27,7 +27,7 @@ module Transpec
         front, rear = build_wrapper_codes
 
         insert_before(beginning_of_line_range(block_node), front)
-        replace(expression_range, 'it')
+        replace(range_from_its_to_front_of_block, 'it ')
         insert_after(block_node.loc.expression, rear)
 
         register_record
@@ -89,6 +89,10 @@ module Transpec
         @base_indentation ||= indentation_of_line(node)
       end
 
+      def range_from_its_to_front_of_block
+        expression_range.join(block_node.loc.begin.begin)
+      end
+
       def register_record
         report.records << Record.new(original_syntax, converted_syntax)
       end

data/lib/transpec/syntax/rspec_configure.rb

@@ -26,13 +26,43 @@ module Transpec
       end
 
       def expose_dsl_globally=(boolean)
-        set_config!(:expose_dsl_globally, boolean)
+        comment = <<-END.gsub(/^\s+\|/, '').chomp
+          |Setting this config option `false` removes rspec-core's monkey patching of the
+          |top level methods like `describe`, `shared_examples_for` and `shared_context`
+          |on `main` and `Module`. The methods are always available through the `RSpec`
+          |module like `RSpec.describe` regardless of this setting.
+          |For backwards compatibility this defaults to `true`.
+          |
+          |https://relishapp.com/rspec/rspec-core/v/3-0/docs/configuration/global-namespace-dsl
+        END
+        set_config!(:expose_dsl_globally, boolean, comment)
       end
 
       def infer_spec_type_from_file_location!
         return if infer_spec_type_from_file_location?
         return unless rspec_rails?
-        add_config!(:infer_spec_type_from_file_location!)
+
+        # rubocop:disable LineLength
+        #
+        # Based on the deprecation warning in RSpec 2.99:
+        # https://github.com/rspec/rspec-rails/blob/ab6313b/lib/rspec/rails/infer_type_configuration.rb#L13-L22
+        # and the Myron's post:
+        # http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3#filetype_inference_disabled_by_default
+        #
+        # rubocop:enable LineLength
+        comment = <<-END.gsub(/^\s+\|/, '').chomp
+          |rspec-rails 3 will no longer automatically infer an example group's spec type
+          |from the file location. You can explicitly opt-in to the feature using this
+          |config option.
+          |To explicitly tag specs without using automatic inference, set the `:type`
+          |metadata manually:
+          |
+          |    describe ThingsController, :type => :controller do
+          |      # Equivalent to being in spec/controllers
+          |    end
+        END
+
+        add_config!(:infer_spec_type_from_file_location!, nil, comment)
       end
 
       def infer_spec_type_from_file_location?

data/lib/transpec/syntax/rspec_configure/config_modification.rb

@@ -15,14 +15,14 @@ module Transpec
 
         private
 
-        def set_config!(config_name, value)
+        def set_config!(config_name, value, comment = nil)
           setter_node = find_config_node("#{config_name}=")
 
           if setter_node
             arg_node = setter_node.children[2]
             source_rewriter.replace(arg_node.loc.expression, value.to_s)
           else
-            add_config!(config_name, value)
+            add_config!(config_name, value, comment)
           end
         end
 
@@ -46,8 +46,8 @@ module Transpec
 
         # TODO: Refactor this to remove messy overrides in Framework.
         module ConfigAddition
-          def add_config!(config_name, value = nil)
-            lines = generate_config_lines(config_name, value)
+          def add_config!(config_name, value = nil, comment = nil)
+            lines = generate_config_lines(config_name, value, comment)
             lines.unshift('') unless empty_block_body?
             lines.map! { |line| line + "\n" }
 
@@ -57,10 +57,21 @@ module Transpec
             block_node_to_insert_code.metadata[:added_config] = true
           end
 
-          def generate_config_lines(config_name, value = nil)
-            line = body_indentation + "#{config_variable_name}.#{config_name}"
-            line << " = #{value}" unless value.nil?
-            [line]
+          def generate_config_lines(config_name, value = nil, comment = nil)
+            lines = []
+
+            if comment
+              comment_lines = comment.each_line.map do |line|
+                "#{body_indentation}# #{line.chomp}".rstrip
+              end
+              lines.concat(comment_lines)
+            end
+
+            config_line = body_indentation + "#{config_variable_name}.#{config_name}"
+            config_line << " = #{value}" unless value.nil?
+            lines << config_line
+
+            lines
           end
 
           def config_variable_name

data/lib/transpec/syntax/rspec_configure/framework.rb

@@ -34,7 +34,7 @@ module Transpec
           fail NotImplementedError
         end
 
-        def generate_config_lines(config_name, value = nil)
+        def generate_config_lines(config_name, value = nil, comment = nil)
           lines = super
 
           unless block_node

data/lib/transpec/syntax/rspec_configure/mocks.rb

@@ -11,7 +11,22 @@ module Transpec
         end
 
         def yield_receiver_to_any_instance_implementation_blocks=(boolean)
-          set_config!(:yield_receiver_to_any_instance_implementation_blocks, boolean)
+          # rubocop:disable LineLength
+          #
+          # Based on the deprecation warning in RSpec 2.99:
+          # https://github.com/rspec/rspec-mocks/blob/aab8dc9/lib/rspec/mocks/message_expectation.rb#L478-L491
+          #
+          # rubocop:enable LineLength
+          comment = <<-END.gsub(/^\s+\|/, '').chomp
+            |In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
+            |instance as the first block argument to allow the implementation block to use
+            |the state of the receiver.
+            |In RSpec 2.99, to maintain compatibility with RSpec 3 you need to either set
+            |this config option to `false` OR set this to `true` and update your
+            |`any_instance` implementation blocks to account for the first block argument
+            |being the receiving instance.
+          END
+          set_config!(:yield_receiver_to_any_instance_implementation_blocks, boolean, comment)
         end
       end
     end

data/lib/transpec/version.rb

@@ -4,7 +4,7 @@ module Transpec
   # http://semver.org/
   module Version
     MAJOR = 2
-    MINOR = 1
+    MINOR = 2
     PATCH = 0
 
     def self.to_s

data/spec/acceptance/configuration_modification_spec.rb

@@ -48,6 +48,13 @@ module Transpec
         File.read('spec/spec_helper.rb').should == <<-END
           RSpec.configure do |config|
             config.mock_with :rspec do |mocks|
+              # In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
+              # instance as the first block argument to allow the implementation block to use
+              # the state of the receiver.
+              # In RSpec 2.99, to maintain compatibility with RSpec 3 you need to either set
+              # this config option to `false` OR set this to `true` and update your
+              # `any_instance` implementation blocks to account for the first block argument
+              # being the receiving instance.
               mocks.yield_receiver_to_any_instance_implementation_blocks = true
             end
           end
@@ -97,6 +104,13 @@ module Transpec
             File.read(spec_helper_path).should == <<-END
           RSpec.configure do |config|
             config.mock_with :rspec do |mocks|
+              # In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
+              # instance as the first block argument to allow the implementation block to use
+              # the state of the receiver.
+              # In RSpec 2.99, to maintain compatibility with RSpec 3 you need to either set
+              # this config option to `false` OR set this to `true` and update your
+              # `any_instance` implementation blocks to account for the first block argument
+              # being the receiving instance.
               mocks.yield_receiver_to_any_instance_implementation_blocks = true
             end
           end

data/spec/transpec/option_parser_spec.rb

@@ -172,13 +172,34 @@ module Transpec
         end
       end
 
-      describe '-p/--no-parentheses-matcher-arg option' do
+      describe '-p/--no-parens-matcher-arg option' do
+        let(:args) { ['--no-parens-matcher-arg'] }
+
+        it 'sets Config#parenthesize_matcher_arg? false' do
+          parser.parse(args)
+          config.parenthesize_matcher_arg.should be_false
+        end
+      end
+
+      describe '--no-parentheses-matcher-arg option' do
         let(:args) { ['--no-parentheses-matcher-arg'] }
 
+        before do
+          parser.stub(:warn)
+        end
+
         it 'sets Config#parenthesize_matcher_arg? false' do
           parser.parse(args)
           config.parenthesize_matcher_arg.should be_false
         end
+
+        it 'is deprecated' do
+          parser.should_receive(:warn) do |message|
+            message.should =~ /--no-parentheses-matcher-arg.+deprecated/i
+          end
+
+          parser.parse(args)
+        end
       end
 
       describe '--no-color option' do

data/spec/transpec/syntax/its_spec.rb

@@ -92,6 +92,34 @@ module Transpec
             record.converted_syntax.should == "describe '#attr' do subject { super().attr }; it { } end"
           end
 
+          context 'and there are consecutive blanks between the #its and the block' do
+            let(:source) do
+              <<-END
+                describe 'example' do
+                  subject { ['foo'] }
+                  its(:size)   { should == 1 }
+                end
+              END
+            end
+
+            let(:expected_source) do
+              <<-END
+                describe 'example' do
+                  subject { ['foo'] }
+
+                  describe '#size' do
+                    subject { super().size }
+                    it { should == 1 }
+                  end
+                end
+              END
+            end
+
+            it 'removes the redundant blanks' do
+              rewritten_source.should == expected_source
+            end
+          end
+
           context 'and there is no blank line before #its' do
             context 'and the indentation level of the previous line is same as the target line' do
               let(:source) do

data/spec/transpec/syntax/rspec_configure_spec.rb

@@ -25,8 +25,24 @@ module Transpec
         let(:expected_source) do
           <<-END
             RSpec.configure do |config|
+              # Setting this config option `false` removes rspec-core's monkey patching of the
+              # top level methods like `describe`, `shared_examples_for` and `shared_context`
+              # on `main` and `Module`. The methods are always available through the `RSpec`
+              # module like `RSpec.describe` regardless of this setting.
+              # For backwards compatibility this defaults to `true`.
+              #
+              # https://relishapp.com/rspec/rspec-core/v/3-0/docs/configuration/global-namespace-dsl
               config.expose_dsl_globally = true
 
+              # rspec-rails 3 will no longer automatically infer an example group's spec type
+              # from the file location. You can explicitly opt-in to the feature using this
+              # config option.
+              # To explicitly tag specs without using automatic inference, set the `:type`
+              # metadata manually:
+              #
+              #     describe ThingsController, :type => :controller do
+              #       # Equivalent to being in spec/controllers
+              #     end
               config.infer_spec_type_from_file_location!
             end
           END
@@ -75,12 +91,19 @@ module Transpec
           let(:expected_source) do
             <<-END
               RSpec.configure do |config|
+                # Setting this config option `false` removes rspec-core's monkey patching of the
+                # top level methods like `describe`, `shared_examples_for` and `shared_context`
+                # on `main` and `Module`. The methods are always available through the `RSpec`
+                # module like `RSpec.describe` regardless of this setting.
+                # For backwards compatibility this defaults to `true`.
+                #
+                # https://relishapp.com/rspec/rspec-core/v/3-0/docs/configuration/global-namespace-dsl
                 config.expose_dsl_globally = true
               end
             END
           end
 
-          it 'adds #expose_dsl_globally= statement' do
+          it 'adds #expose_dsl_globally= statement along with comment' do
             rewritten_source.should == expected_source
           end
         end
@@ -99,6 +122,13 @@ module Transpec
               RSpec.configure do |config|
                 config.foo = 1
 
+                # Setting this config option `false` removes rspec-core's monkey patching of the
+                # top level methods like `describe`, `shared_examples_for` and `shared_context`
+                # on `main` and `Module`. The methods are always available through the `RSpec`
+                # module like `RSpec.describe` regardless of this setting.
+                # For backwards compatibility this defaults to `true`.
+                #
+                # https://relishapp.com/rspec/rspec-core/v/3-0/docs/configuration/global-namespace-dsl
                 config.expose_dsl_globally = true
               end
             END
@@ -126,12 +156,21 @@ module Transpec
           let(:expected_source) do
             <<-END
               RSpec.configure do |config|
+                # rspec-rails 3 will no longer automatically infer an example group's spec type
+                # from the file location. You can explicitly opt-in to the feature using this
+                # config option.
+                # To explicitly tag specs without using automatic inference, set the `:type`
+                # metadata manually:
+                #
+                #     describe ThingsController, :type => :controller do
+                #       # Equivalent to being in spec/controllers
+                #     end
                 config.infer_spec_type_from_file_location!
               end
             END
           end
 
-          it 'adds #infer_spec_type_from_file_location! statement' do
+          it 'adds #infer_spec_type_from_file_location! statement along with comment' do
             rewritten_source.should == expected_source
           end
         end
@@ -174,6 +213,15 @@ module Transpec
                 end
 
                 RSpec.configure do |config|
+                  # rspec-rails 3 will no longer automatically infer an example group's spec type
+                  # from the file location. You can explicitly opt-in to the feature using this
+                  # config option.
+                  # To explicitly tag specs without using automatic inference, set the `:type`
+                  # metadata manually:
+                  #
+                  #     describe ThingsController, :type => :controller do
+                  #       # Equivalent to being in spec/controllers
+                  #     end
                   config.infer_spec_type_from_file_location!
                 end
               END
@@ -498,13 +546,20 @@ module Transpec
               <<-END
                 RSpec.configure do |config|
                   config.mock_with :rspec do |c|
+                    # In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
+                    # instance as the first block argument to allow the implementation block to use
+                    # the state of the receiver.
+                    # In RSpec 2.99, to maintain compatibility with RSpec 3 you need to either set
+                    # this config option to `false` OR set this to `true` and update your
+                    # `any_instance` implementation blocks to account for the first block argument
+                    # being the receiving instance.
                     c.yield_receiver_to_any_instance_implementation_blocks = true
                   end
                 end
               END
             end
 
-            it 'adds #yield_receiver_to_any_instance_implementation_blocks= statement' do
+            it 'adds #yield_receiver_to_any_instance_implementation_blocks= statement along with comment' do
               rewritten_source.should == expected_source
             end
           end
@@ -523,6 +578,13 @@ module Transpec
               <<-END
                 RSpec.configure do |config|
                   config.mock_with :rspec do |mocks|
+                    # In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
+                    # instance as the first block argument to allow the implementation block to use
+                    # the state of the receiver.
+                    # In RSpec 2.99, to maintain compatibility with RSpec 3 you need to either set
+                    # this config option to `false` OR set this to `true` and update your
+                    # `any_instance` implementation blocks to account for the first block argument
+                    # being the receiving instance.
                     mocks.yield_receiver_to_any_instance_implementation_blocks = true
                   end
                 end
@@ -530,7 +592,7 @@ module Transpec
             end
 
             it 'adds #mock_with block ' \
-               'and #yield_receiver_to_any_instance_implementation_blocks= statement' do
+               'and #yield_receiver_to_any_instance_implementation_blocks= statement along with comment' do
               rewritten_source.should == expected_source
             end
 
@@ -546,6 +608,13 @@ module Transpec
                 <<-END
                   RSpec.configure do |mocks|
                     mocks.mock_with :rspec do |config|
+                      # In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
+                      # instance as the first block argument to allow the implementation block to use
+                      # the state of the receiver.
+                      # In RSpec 2.99, to maintain compatibility with RSpec 3 you need to either set
+                      # this config option to `false` OR set this to `true` and update your
+                      # `any_instance` implementation blocks to account for the first block argument
+                      # being the receiving instance.
                       config.yield_receiver_to_any_instance_implementation_blocks = true
                     end
                   end
@@ -576,9 +645,23 @@ module Transpec
         let(:expected_source) do
           <<-END
             RSpec.configure do |config|
+              # Setting this config option `false` removes rspec-core's monkey patching of the
+              # top level methods like `describe`, `shared_examples_for` and `shared_context`
+              # on `main` and `Module`. The methods are always available through the `RSpec`
+              # module like `RSpec.describe` regardless of this setting.
+              # For backwards compatibility this defaults to `true`.
+              #
+              # https://relishapp.com/rspec/rspec-core/v/3-0/docs/configuration/global-namespace-dsl
               config.expose_dsl_globally = true
 
               config.mock_with :rspec do |mocks|
+                # In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
+                # instance as the first block argument to allow the implementation block to use
+                # the state of the receiver.
+                # In RSpec 2.99, to maintain compatibility with RSpec 3 you need to either set
+                # this config option to `false` OR set this to `true` and update your
+                # `any_instance` implementation blocks to account for the first block argument
+                # being the receiving instance.
                 mocks.yield_receiver_to_any_instance_implementation_blocks = false
               end
             end

data/transpec.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'activesupport', '>= 3.0', '< 5.0'
 
   spec.add_development_dependency 'rake',          '~> 10.1'
-  spec.add_development_dependency 'rspec',         '~> 2.14'
+  spec.add_development_dependency 'rspec',         '~> 2.14.0'
   spec.add_development_dependency 'fuubar',        '~> 1.3'
   spec.add_development_dependency 'simplecov',     '~> 0.7'
   spec.add_development_dependency 'rubocop',       '~> 0.19'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: transpec
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Yuji Nakayama
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-23 00:00:00.000000000 Z
+date: 2014-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parser
@@ -118,14 +118,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.14'
+        version: 2.14.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.14'
+        version: 2.14.0
 - !ruby/object:Gem::Dependency
   name: fuubar
   requirement: !ruby/object:Gem::Requirement