summaryrefslogtreecommitdiff
path: root/lib/rubygems/deprecate.rb
diff options
context:
space:
mode:
Diffstat (limited to 'lib/rubygems/deprecate.rb')
-rw-r--r--lib/rubygems/deprecate.rb96
1 files changed, 73 insertions, 23 deletions
diff --git a/lib/rubygems/deprecate.rb b/lib/rubygems/deprecate.rb
index 8c822cda95..58a6c5b7dc 100644
--- a/lib/rubygems/deprecate.rb
+++ b/lib/rubygems/deprecate.rb
@@ -1,28 +1,75 @@
# frozen_string_literal: true
+
##
-# Provides a single method +deprecate+ to be used to declare when
-# something is going away.
+# 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.klass_method
+# def self.some_class_method
+# # ...
+# end
+#
+# def some_instance_method
# # ...
# end
#
-# def instance_method
+# def some_old_method
# # ...
# end
#
# extend Gem::Deprecate
-# deprecate :instance_method, "X.z", 2011, 4
+# deprecate :some_instance_method, "X.z", 2011, 4
+# rubygems_deprecate :some_old_method, "Modern#some_new_method"
#
# class << self
# extend Gem::Deprecate
-# deprecate :klass_method, :none, 2011, 4
+# 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
module Gem::Deprecate
-
def self.skip # :nodoc:
@skip ||= false
end
@@ -35,7 +82,8 @@ module Gem::Deprecate
# Temporarily turn off warnings. Intended for tests only.
def skip_during
- Gem::Deprecate.skip, original = true, Gem::Deprecate.skip
+ original = Gem::Deprecate.skip
+ Gem::Deprecate.skip = true
yield
ensure
Gem::Deprecate.skip = original
@@ -56,12 +104,13 @@ module Gem::Deprecate
old = "_deprecated_#{name}"
alias_method old, name
define_method name do |*args, &block|
- klass = self.kind_of? Module
+ klass = is_a? 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(":")}",
+ 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
@@ -81,12 +130,13 @@ module Gem::Deprecate
old = "_deprecated_#{name}"
alias_method old, name
define_method name do |*args, &block|
- klass = self.kind_of? Module
+ 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(":")}",
+ 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
@@ -96,22 +146,22 @@ module Gem::Deprecate
end
# Deprecation method to deprecate Rubygems commands
- def rubygems_deprecate_command
+ 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 #{Gem::Deprecate.next_rubygems_major_version}.\n",
+ msg = [
+ "#{command} command is deprecated",
+ ". It will be removed in Rubygems #{version}.\n",
]
- alert_warning "#{msg.join}" unless Gem::Deprecate.skip
+ alert_warning msg.join.to_s unless Gem::Deprecate.skip
end
end
end
module_function :rubygems_deprecate, :rubygems_deprecate_command, :skip_during
-
end