Deprecation formatter

Changelog.md

@@ -40,8 +40,8 @@ Enhancements
   allow access to `Time.now` (Jon Rowe)
 * Make `shared_examples_for` context aware, so that keys may be safely reused
   in multiple contexts without colliding. (Jon Rowe)
-* Make `warn_deprecations` use a configurable `deprecation_io` stream.
-  (Jon Rowe)
+* Add a configurable `deprecation_stream` (Jon Rowe)
+* Publish deprecations through a formatter (David Chelimsky)
 
 Bug fixes
 

features/command_line/format_option.feature

@@ -2,30 +2,24 @@ Feature: --format option
 
   Use the --format option to tell RSpec how to format the output.
 
-  RSpec ships with a few formatters built in. By default, it uses the progress
+  RSpec ships with several formatters built in. By default, it uses the progress
   formatter, which generates output like this:
 
       ....F.....*.....
 
   A '.' represents a passing example, 'F' is failing, and '*' is pending.
 
-  To see the documentation strings passed to each describe(), context(), and it()
-  method, use the documentation formatter:
+  Use the documentation formatter to see the documentation strings passed to
+  `describe`, `it`, and their aliases:
 
       $ rspec spec --format documentation
 
-  You can also specify an output target (STDOUT by default) by appending a
-  filename to the argument:
+  You can also specify an output target ($stdout by default) with an --out
+  option immediately following the --format option:
 
-    $ rspec spec --format documentation --out rspec.txt
+      $ rspec spec --format documentation --out rspec.txt
 
-  `rspec --help` lists available formatters:
-
-      [p]rogress (default - dots)
-      [d]ocumentation (group and example names)
-      [h]tml
-      [t]extmate
-      custom formatter class name
+  Run `rspec --help` to see a listing of available formatters.
 
   Background:
     Given a file named "example_spec.rb" with:
@@ -69,7 +63,7 @@ Feature: --format option
         does something that is pending (PENDING: No reason given)
       """
 
-  Scenario: multiple formats
+  Scenario: multiple formats and output targets
     When I run `rspec example_spec.rb --format progress --format documentation --out rspec.txt`
     Then the output should contain ".F*"
     And the file "rspec.txt" should contain:

features/configuration/deprecation_stream.feature

@@ -0,0 +1,58 @@
+Feature: deprecation_stream
+
+  Define a custom output stream for warning about deprecations (default `$stderr`).
+
+    RSpec.configure {|c| c.deprecation_stream = File.open('deprecations.txt', 'w') }
+
+  or
+
+    RSpec.configure {|c| c.deprecation_stream = 'deprecations.txt' }
+
+  Background:
+    Given a file named "lib/foo.rb" with:
+      """ruby
+      class Foo
+        def bar
+          RSpec.deprecate "Foo#bar"
+        end
+      end
+      """
+
+  Scenario: default - print deprecations to $stderr
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require "foo"
+      describe "calling a deprecated method" do
+        example { Foo.new.bar }
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the output should contain "DEPRECATION: Foo#bar is deprecated"
+
+  Scenario: configure using the path to a file
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require "foo"
+      RSpec.configure {|c| c.deprecation_stream = 'deprecations.txt' }
+      describe "calling a deprecated method" do
+        example { Foo.new.bar }
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the output should not contain "DEPRECATION"
+    But the output should contain "1 deprecation logged to deprecations.txt"
+    And the file "deprecations.txt" should contain "Foo#bar is deprecated"
+
+  Scenario: configure using a File object
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require "foo"
+      RSpec.configure {|c| c.deprecation_stream = File.open('deprecations.txt', 'w') }
+      describe "calling a deprecated method" do
+        example { Foo.new.bar }
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the output should not contain "DEPRECATION"
+    But the output should contain "1 deprecation logged to deprecations.txt"
+    And the file "deprecations.txt" should contain "Foo#bar is deprecated"

lib/rspec/core.rb

@@ -17,7 +17,6 @@
 require_rspec['core/extensions/instance_eval_with_args']
 require_rspec['core/extensions/module_eval_with_args']
 require_rspec['core/extensions/ordered']
-require_rspec['core/deprecation_io']
 require_rspec['core/deprecation']
 require_rspec['core/backward_compatibility']
 require_rspec['core/reporter']

lib/rspec/core/backward_compatibility.rb

@@ -7,17 +7,7 @@ module ConstMissing
       def const_missing(name)
         case name
         when :Rspec, :Spec
-          RSpec.warn_deprecation <<-WARNING
-*****************************************************************
-DEPRECATION WARNING: you are using a deprecated constant that will
-be removed from a future version of RSpec.
-
-#{caller(0)[2]}
-
-* #{name} is deprecated.
-* RSpec is the new top-level module in RSpec-2
-*****************************************************************
-WARNING
+          RSpec.deprecate(name.to_s, :replacement => "RSpec")
           RSpec
         else
           begin
@@ -34,7 +24,7 @@ def const_missing(name)
   module Runner
     # @deprecated use RSpec.configure instead.
     def self.configure(&block)
-      RSpec.deprecate("Spec::Runner.configure", "RSpec.configure")
+      RSpec.deprecate("Spec::Runner.configure", :replacement => "RSpec.configure")
       RSpec.configure(&block)
     end
   end
@@ -46,7 +36,7 @@ module Rake
     def self.const_missing(name)
       case name
       when :SpecTask
-        RSpec.deprecate("Spec::Rake::SpecTask", "RSpec::Core::RakeTask")
+        RSpec.deprecate("Spec::Rake::SpecTask", :replacement => "RSpec::Core::RakeTask")
         require 'rspec/core/rake_task'
         RSpec::Core::RakeTask
       else

lib/rspec/core/configuration.rb

@@ -1,6 +1,7 @@
 require 'fileutils'
 require 'rspec/core/backtrace_cleaner'
 require 'rspec/core/ruby_project'
+require 'rspec/core/formatters/deprecation_formatter.rb'
 
 module RSpec
   module Core
@@ -42,10 +43,7 @@ def self.define_reader(name)
 
       # @private
       def self.deprecate_alias_key
-        RSpec.warn_deprecation <<-MESSAGE
-The :alias option to add_setting is deprecated. Use :alias_with on the original setting instead.
-Called from #{caller(0)[5]}
-MESSAGE
+        RSpec.deprecate("add_setting with :alias option", :replacement => ":alias_with")
       end
 
       # @private
@@ -97,6 +95,9 @@ def self.add_setting(name, opts={})
       # Default: `$stderr`.
       add_setting :error_stream
 
+      # Default: `$stderr`.
+      add_setting :deprecation_stream
+
       # Clean up and exit after the first failure (default: `false`).
       add_setting :fail_fast
 
@@ -195,7 +196,7 @@ def initialize
         @backtrace_cleaner = BacktraceCleaner.new
 
         @default_path = 'spec'
-        @deprecation_io = DeprecationIO.new
+        @deprecation_stream = $stderr
         @filter_manager = FilterManager.new
         @preferred_options = {}
         @seed = srand % 0xFFFF
@@ -272,18 +273,6 @@ def add_setting(name, opts={})
         send("#{name}=", default) if default
       end
 
-      # Set the io used for deprection warnings
-      # Defaults to $stderr
-      def deprecation_io=(value)
-        @deprecation_io.set_output value
-      end
-      attr_reader :deprecation_io
-
-      # Set a file to be the io for deprection warnings
-      def log_deprecations_to_file name
-        @deprecation_io.set_output File.open(name,'w+'), name
-      end
-
       # Returns the configured mock framework adapter module
       def mock_framework
         mock_with :rspec unless @mock_framework
@@ -308,13 +297,13 @@ def mock_framework=(framework)
       # `rspec_options` attribute of RSpec's rake task.
       def backtrace_clean_patterns
         RSpec.deprecate("RSpec::Core::Configuration#backtrace_clean_patterns",
-                        "RSpec::Core::Configuration#backtrace_exclusion_patterns")
+                        :replacement => "RSpec::Core::Configuration#backtrace_exclusion_patterns")
         @backtrace_cleaner.exclusion_patterns
       end
 
       def backtrace_clean_patterns=(patterns)
         RSpec.deprecate("RSpec::Core::Configuration#backtrace_clean_patterns",
-                        "RSpec::Core::Configuration#backtrace_exclusion_patterns")
+                        :replacement => "RSpec::Core::Configuration#backtrace_exclusion_patterns")
         @backtrace_cleaner.exclusion_patterns = patterns
       end
 
@@ -521,7 +510,7 @@ def libs=(libs)
 
       def requires=(paths)
         RSpec.deprecate("RSpec::Core::Configuration#requires=(paths)",
-                        "paths.each {|path| require path}")
+                        :replacement => "paths.each {|path| require path}")
         paths.map {|path| require path}
         @requires += paths
       end
@@ -577,15 +566,16 @@ def full_description
       # ### Note
       #
       # For internal purposes, `add_formatter` also accepts the name of a class
-      # and path to a file that contains that class definition, but you should
-      # consider that a private api that may change at any time without notice.
-      def add_formatter(formatter_to_use, path=nil)
+      # and paths to use for output streams, but you should consider that a
+      # private api that may change at any time without notice.
+      def add_formatter(formatter_to_use, *paths)
         formatter_class =
           built_in_formatter(formatter_to_use) ||
           custom_formatter(formatter_to_use) ||
           (raise ArgumentError, "Formatter '#{formatter_to_use}' unknown - maybe you meant 'documentation' or 'progress'?.")
 
-        formatters << formatter_class.new(path ? file_at(path) : output)
+        paths << output if paths.empty?
+        formatters << formatter_class.new(*paths.map {|p| String === p ? file_at(p) : p})
       end
 
       alias_method :formatter=, :add_formatter
@@ -597,6 +587,7 @@ def formatters
       def reporter
         @reporter ||= begin
                         add_formatter('progress') if formatters.empty?
+                        add_formatter(RSpec::Core::Formatters::DeprecationFormatter, deprecation_stream, output_stream)
                         Reporter.new(*formatters)
                       end
       end

lib/rspec/core/deprecation.rb

@@ -1,47 +1,24 @@
 module RSpec
-  class << self
-    # @private
-    #
-    # Used internally to print deprecation warnings
-    def deprecate(method, alternate_method=nil, version=nil)
-      lines = ["#{method} is deprecated"]
-      if version
-        lines.last << ", and will be removed from rspec-#{version}"
+  module Core
+    module Deprecation
+      # @private
+      #
+      # Used internally to print deprecation warnings
+      def deprecate(deprecated, replacement_or_hash={}, ignore_version=nil)
+        # Temporarily support old and new APIs while we transition the other
+        # rspec libs to use a hash for the 2nd arg and no version arg
+        data = Hash === replacement_or_hash ? replacement_or_hash : { :replacement => replacement_or_hash }
+        RSpec.configuration.reporter.deprecation data.merge(:deprecated => deprecated, :call_site => caller(0)[2])
       end
-      if alternate_method
-        lines << "use #{alternate_method} instead"
-      end
-
-      lines << "called from #{caller(0)[2]}"
-
-      warn_deprecation "\n" + lines.map {|l| "DEPRECATION: #{l}"}.join("\n") + "\n"
-    end
-
-    # @private
-    #
-    # Used internally to print deprecation warnings
-    def warn_deprecation(message)
-      RSpec.configuration.deprecation_io.puts(message)
-    end
-
-    # @private
-    #
-    # Used internally to print the count of deprecation warnings
-    def deprecations?
-      RSpec.configuration.deprecation_io.deprecations > 0
-    end
 
-    # @private
-    #
-    # Used internally to print deprecation summary
-    def deprecations_summary
-      io = RSpec.configuration.deprecation_io
-      if io.deprecations == 1
-        "There was 1 deprecation logged to #{io.description}"
-      else
-        "There were #{io.deprecations} deprecations logged to #{io.description}"
+      # @private
+      #
+      # Used internally to print deprecation warnings
+      def warn_deprecation(message)
+        RSpec.configuration.reporter.deprecation :message => message
       end
     end
-
   end
+
+  extend(Core::Deprecation)
 end