module Gem::Deprecate - Documentation for Ruby 3.2

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

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.

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

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 lib/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 lib/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 lib/rubygems/deprecate.rb, line 85
    def skip_during
      Gem::Deprecate.skip, original = true, Gem::Deprecate.skip
      yield
    ensure
      Gem::Deprecate.skip = original
    end