🔍

No recent searches

# 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, 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

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.

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

Deprecation method to deprecate Rubygems commands

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

Temporarily turn off warnings. Intended for tests only.

### 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

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.

### Private Instance 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

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.

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

Deprecation method to deprecate Rubygems commands

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

Temporarily turn off warnings. Intended for tests only.