Important

I archived this repo here and moved it to Codeberg for several reasons.
🛠️ It's still active there!

Deprecations

This gem provides transparent declaration of deprecated methods and classes. It's easy, small, has no dependencies and no overhead.

• Gem: rubygems.org
• Source: codeberg.org

Installation

The simplest way to install Deprecations gem is to use Bundler.

Add Deprecations to your Gemfile:

gem 'deprecations'

and install it by running Bundler:

$ bundle add deprecations

To install the gem globally use:

$ gem install deprecations

Usage

After adding the gem to your project

require 'deprecations'

you can specify which methods and classes are deprecated. To mark a method as deprecated is quite easy:

class MySample
  def clear
    # something here
  end

  def clean
    clear
  end

  deprecated :clean, :clear, 'next version'
end

Whenever the method MySample#clean is called this warning appears:

warning: MySample#clean is deprecated and will be outdated next version. Please use MySample#clear instead.

Marking a complete class as deprecated will present the deprecation warning whenever this class is instantiated:

class MySample
  deprecated!

  # some more code here...
end

You can change the behavior of notifying:

Deprecations.behavior = :raise

There are 3 pre-defined behaviors:

• :raise will raise an Deprecations::Exception when a deprecated method is called
• :silence will do nothing (ignore the deprecation)
• :warn will print a warning (default behavior)
• :deprecated will print a warning when Ruby's warning category 'deprecated' is enabled

Besides this you can implement your own:

Deprecations.behavior =
  proc do |subject, _alternative, _outdated|
    SuperLogger.warning "deprecated: #{subject}"
  end

Any object responding to #call will be accepted as a valid handler.

Whenever you need to temporary change the standard behavior (like e.g. in your specs) you can do this like

Deprecations.with_behavior(:silent) { MyDeprecatedClass.new.do_some_magic }

Please have a look at the specs for detailed information and more samples.