module Gem::Deprecate

提供 3 种声明某个内容即将移除的方法。

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.

还提供了 skip_during 方法，用于临时关闭弃用警告。此方法 intended for use in the test suite, 这样在需要确保 stderr 为空时，弃用警告就不会导致测试失败。

deprecate 和 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

rubygems_deprecate_command 的示例用法

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

  # ...
end

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, version = nil)

Source

# File lib/rubygems/deprecate.rb, line 129
def rubygems_deprecate(name, replacement = :none, version = nil)
  class_eval do
    old = "_deprecated_#{name}"
    alias_method old, name
    define_method name do |*args, &block|
      klass = is_a? Module
      target = klass ? "#{self}." : "#{self.class}#"
      version ||= Gem::Deprecate.next_rubygems_major_version
      msg = [
        "NOTE: #{target}#{name} is deprecated",
        replacement == :none ? " with no replacement" : "; use #{replacement} instead",
        ". It will be removed in Rubygems #{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

简单的弃用方法，通过将其包装在一个 dummy 方法中来弃用 name。每次调用 dummy 方法时，它都会发出警告，告知用户 repl（除非 repl 是 :none）以及将在哪个 Rubygems 版本中移除。

rubygems_deprecate_command (version = nil)

Source

# File lib/rubygems/deprecate.rb, line 151
def rubygems_deprecate_command(version = nil)
  class_eval do
    define_method "deprecated?" do
      true
    end

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

      alert_warning msg.join.to_s unless Gem::Deprecate.skip
    end
  end
end

弃用 Rubygems 命令的方法

skip_during () { || ... }

Source

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

临时关闭警告。仅 intended for tests。

Public Instance Methods

deprecate (name, repl, year, month)

Source

# File lib/rubygems/deprecate.rb, line 103
def deprecate(name, repl, year, month)
  class_eval do
    old = "_deprecated_#{name}"
    alias_method old, name
    define_method name do |*args, &block|
      klass = is_a? Module
      target = klass ? "#{self}." : "#{self.class}#"
      msg = [
        "NOTE: #{target}#{name} is deprecated",
        repl == :none ? " with no replacement" : "; use #{repl} instead",
        format(". 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

简单的弃用方法，通过将其包装在一个 dummy 方法中来弃用 name。每次调用 dummy 方法时，它都会发出警告，告知用户 repl（除非 repl 是 :none）以及将在哪一年/哪一月移除。

私有实例方法

rubygems_deprecate (name, replacement = :none, version = nil)

Source

# File lib/rubygems/deprecate.rb, line 129
def rubygems_deprecate(name, replacement = :none, version = nil)
  class_eval do
    old = "_deprecated_#{name}"
    alias_method old, name
    define_method name do |*args, &block|
      klass = is_a? Module
      target = klass ? "#{self}." : "#{self.class}#"
      version ||= Gem::Deprecate.next_rubygems_major_version
      msg = [
        "NOTE: #{target}#{name} is deprecated",
        replacement == :none ? " with no replacement" : "; use #{replacement} instead",
        ". It will be removed in Rubygems #{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 = nil)

Source

# File lib/rubygems/deprecate.rb, line 151
def rubygems_deprecate_command(version = nil)
  class_eval do
    define_method "deprecated?" do
      true
    end

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

      alert_warning msg.join.to_s unless Gem::Deprecate.skip
    end
  end
end

弃用 Rubygems 命令的方法

skip_during () { || ... }

Source

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

临时关闭警告。仅 intended for tests。