123456789_123456789_123456789_123456789_123456789_

Module: Gem::Deprecate

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Extended In:
BasicSpecification, Commands::QueryCommand, ConsoleUI, DependencyInstaller, Installer, Platform, SilentUI, Specification, StreamUI, StubSpecification, 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 Attribute Summary

Class Method Summary

Instance Method Summary

Class Attribute Details

.skip (rw)

This method is for internal use only.
[ GitHub ] 

  


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



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


  








  

    .skip=(v)   (rw)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



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


  







Class Method Details



  

    .next_rubygems_major_version  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# 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)   (mod_func)
  



  

    

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.


  



  [ GitHub ]


  

  


# 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)   (mod_func)
  



  

    

Deprecation method to deprecate Rubygems commands


  



  [ GitHub ]


  

  


# 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_during   (mod_func)
  



  

    

Temporarily turn off warnings. Intended for tests only.


  



  [ GitHub ]


  

  


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



  

    

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.


  



  [ GitHub ]


  

  


# 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