module Gem::Deprecate

Provides 3 methods for declaring when something is going away.

+deprecate(name, repl, year, month)+:

Indicate something may be removed on/after a certain date.

+rubygems_deprecate(name, replacement=:none)+:

Indicate something will be removed in the next major RubyGems version,
and (optionally) a replacement for it.

rubygems_deprecate_command:

Indicate a RubyGems command (in +lib/rubygems/commands/*.rb+) will be
removed in the next RubyGems version.

Also provides skip_during for temporarily turning off deprecation warnings. This is intended to be used in the test suite, so deprecation warnings don’t cause test failures if you need to make sure stderr is otherwise empty.

Example usage of deprecate and rubygems_deprecate:

class Legacy
  def self.some_class_method
    # ...
  end

  def some_instance_method
    # ...
  end

  def some_old_method
    # ...
  end

  extend Gem::Deprecate
  deprecate :some_instance_method, "X.z", 2011, 4
  rubygems_deprecate :some_old_method, "Modern#some_new_method"

  class << self
    extend Gem::Deprecate
    deprecate :some_class_method, :none, 2011, 4
  end
end

Example usage of rubygems_deprecate_command:

class Gem::Commands::QueryCommand < Gem::Command
  extend Gem::Deprecate
  rubygems_deprecate_command

  # ...
end

Example usage of skip_during:

class TestSomething < Gem::Testcase
  def test_some_thing_with_deprecations
    Gem::Deprecate.skip_during do
      actual_stdout, actual_stderr = capture_output do
        Gem.something_deprecated
      end
      assert_empty actual_stdout
      assert_equal(expected, actual_stderr)
    end
  end
end

Public Class Methods

rubygems_deprecate(name, replacement=:none) click to toggle source

Simple deprecation method that deprecates name by wrapping it up in a dummy method. It warns on each call to the dummy method telling the user of repl (unless repl is :none) and the Rubygems version that it is planned to go away.

# File rubygems/deprecate.rb, line 127
def rubygems_deprecate(name, replacement=:none)
  class_eval do
    old = "_deprecated_#{name}"
    alias_method old, name
    define_method name do |*args, &block|
      klass = self.kind_of? Module
      target = klass ? "#{self}." : "#{self.class}#"
      msg = [ "NOTE: #{target}#{name} is deprecated",
              replacement == :none ? " with no replacement" : "; use #{replacement} instead",
              ". It will be removed in Rubygems #{Gem::Deprecate.next_rubygems_major_version}",
              "\n#{target}#{name} called from #{Gem.location_of_caller.join(":")}",
      ]
      warn "#{msg.join}." unless Gem::Deprecate.skip
      send old, *args, &block
    end
    ruby2_keywords name if respond_to?(:ruby2_keywords, true)
  end
end

rubygems_deprecate_command(version = Gem::Deprecate.next_rubygems_major_version) click to toggle source

Deprecation method to deprecate Rubygems commands

# File rubygems/deprecate.rb, line 147
def rubygems_deprecate_command(version = Gem::Deprecate.next_rubygems_major_version)
  class_eval do
    define_method "deprecated?" do
      true
    end

    define_method "deprecation_warning" do
      msg = [ "#{self.command} command is deprecated",
              ". It will be removed in Rubygems #{version}.\n",
      ]

      alert_warning "#{msg.join}" unless Gem::Deprecate.skip
    end
  end
end

skip_during() { || ... } click to toggle source

Temporarily turn off warnings. Intended for tests only.

# File rubygems/deprecate.rb, line 85
def skip_during
  Gem::Deprecate.skip, original = true, Gem::Deprecate.skip
  yield
ensure
  Gem::Deprecate.skip = original
end

Public Instance Methods

deprecate(name, repl, year, month) click to toggle source

# File rubygems/deprecate.rb, line 102
def deprecate(name, repl, year, month)
  class_eval do
    old = "_deprecated_#{name}"
    alias_method old, name
    define_method name do |*args, &block|
      klass = self.kind_of? Module
      target = klass ? "#{self}." : "#{self.class}#"
      msg = [ "NOTE: #{target}#{name} is deprecated",
              repl == :none ? " with no replacement" : "; use #{repl} instead",
              ". It will be removed on or after %4d-%02d." % [year, month],
              "\n#{target}#{name} called from #{Gem.location_of_caller.join(":")}",
      ]
      warn "#{msg.join}." unless Gem::Deprecate.skip
      send old, *args, &block
    end
    ruby2_keywords name if respond_to?(:ruby2_keywords, true)
  end
end

Private Instance Methods

rubygems_deprecate(name, replacement=:none) click to toggle source

# File rubygems/deprecate.rb, line 127
def rubygems_deprecate(name, replacement=:none)
  class_eval do
    old = "_deprecated_#{name}"
    alias_method old, name
    define_method name do |*args, &block|
      klass = self.kind_of? Module
      target = klass ? "#{self}." : "#{self.class}#"
      msg = [ "NOTE: #{target}#{name} is deprecated",
              replacement == :none ? " with no replacement" : "; use #{replacement} instead",
              ". It will be removed in Rubygems #{Gem::Deprecate.next_rubygems_major_version}",
              "\n#{target}#{name} called from #{Gem.location_of_caller.join(":")}",
      ]
      warn "#{msg.join}." unless Gem::Deprecate.skip
      send old, *args, &block
    end
    ruby2_keywords name if respond_to?(:ruby2_keywords, true)
  end
end

rubygems_deprecate_command(version = Gem::Deprecate.next_rubygems_major_version) click to toggle source

Deprecation method to deprecate Rubygems commands

# File rubygems/deprecate.rb, line 147
def rubygems_deprecate_command(version = Gem::Deprecate.next_rubygems_major_version)
  class_eval do
    define_method "deprecated?" do
      true
    end

    define_method "deprecation_warning" do
      msg = [ "#{self.command} command is deprecated",
              ". It will be removed in Rubygems #{version}.\n",
      ]

      alert_warning "#{msg.join}" unless Gem::Deprecate.skip
    end
  end
end

skip_during() { || ... } click to toggle source

Temporarily turn off warnings. Intended for tests only.

# File rubygems/deprecate.rb, line 85
def skip_during
  Gem::Deprecate.skip, original = true, Gem::Deprecate.skip
  yield
ensure
  Gem::Deprecate.skip = original
end