module Faker::Deprecator

Provides a way to rename generators, including their namespaces, with a deprecation cycle in which both the old and new names work, but using the old one prints a deprecation message.

Deprecator provides a deprecate_generator method to be used when renaming a generator. For example, let’s say we want to change the following Generator’s name to Faker::NewGenerator:

module Faker
  class Generator
    def self.generate
      "be kind"
    end
  end
end

To rename it, you need to do the update the name and declare the deprecation by including the Deprecator module and using the deprecate_generator method:

module Faker
  class NewGenerator
    def self.generate
      "be kind"
    end
  end

  include Deprecator
  deprecate_generator('DeprecatedGenerator', NewGenerator)
end

The first argument is a constant name (no colons) as a string. It is the name of the constant you want to deprecate.

The second argument is the constant path of the replacement (no colons) as a constant.

For this to work, a const_missing hook is installed. When users reference the deprecated constant, the callback prints the message and constantizes the replacement.

With that in place, references to Faker::Deprecator still work, they evaluate to Faker::NewGenerator now, and trigger a deprecation warning:

Faker::Generator.generate
# DEPRECATION WARNING: Faker::Generator is deprecated. Use Faker::NewGenerator instead
# "be kind"

For testing the deprecations, we provide assert_deprecated and assert_not_deprecated matchers.

There’s also a Faker::Deprecator.skip_warning helper to silence the deprecation messages in the test output. Use it for generators that have lots of tests to avoid too many noise when running the tests.