Module: Gem::Deprecate

Included in:
BasicSpecification, Commands::QueryCommand, DependencyInstaller, Installer, Platform, Specification, StreamUI, Util
Defined in:
lib/rubygems/deprecate.rb

Overview

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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.next_rubygems_major_version ⇒ Object

:nodoc:



92
93
94
 
# File 'lib/rubygems/deprecate.rb', line 92

def self.next_rubygems_major_version # :nodoc:
  Gem::Version.new(Gem.rubygems_version.segments.first).bump
end

.rubygems_deprecate(name, replacement = :none) ⇒ Object

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.



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/rubygems/deprecate.rb', line 128

def rubygems_deprecate(name, replacement=:none)
  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",
        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) ⇒ Object

Deprecation method to deprecate Rubygems commands



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/rubygems/deprecate.rb', line 149

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 = [
        "#{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

.skip ⇒ Object

:nodoc:



73
74
75
 
# File 'lib/rubygems/deprecate.rb', line 73

def self.skip # :nodoc:
  @skip ||= false
end

.skip=(v) ⇒ Object

:nodoc:



77
78
79
 
# File 'lib/rubygems/deprecate.rb', line 77

def self.skip=(v) # :nodoc:
  @skip = v
end

.skip_during ⇒ Object

Temporarily turn off warnings. Intended for tests only.



84
85
86
87
88
89
90
 
# File 'lib/rubygems/deprecate.rb', line 84

def skip_during
  original = Gem::Deprecate.skip
  Gem::Deprecate.skip = true
  yield
ensure
  Gem::Deprecate.skip = original
end

Instance Method Details

#deprecate(name, repl, year, month) ⇒ Object

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 year/month that it is planned to go away.



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/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 = 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