module Dry::Core::Deprecations

An extension for issueing warnings on using deprecated methods.

@example

class Foo
  def self.old_class_api; end
  def self.new_class_api; end

  deprecate_class_method :old_class_api, :new_class_api

  def old_api; end
  def new_api; end

  deprecate :old_api, :new_api, message: "old_api is no-no"
end

@example You also can use this module for your custom messages

Dry::Core::Deprecations.announce("Foo", "use bar instead")
Dry::Core::Deprecations.warn("Baz is going to be removed soon")

@api public

Constants

STACK

Public Class Methods

[](tag) click to toggle source
# File lib/dry/core/deprecations.rb, line 115
def [](tag)
  Tagged.new(tag)
end
announce(name, msg, tag: nil, uplevel: nil) click to toggle source

Wraps arguments with a standard message format and prints a warning

@param [Object] name what is deprecated @param [String] msg additional message usually containing upgrade instructions

# File lib/dry/core/deprecations.rb, line 51
def announce(name, msg, tag: nil, uplevel: nil)
  # Bump the uplevel (if provided) by one to account for the uplevel calculation
  # taking place one frame deeper in `.warn`
  uplevel += 1 if uplevel

  warn(deprecation_message(name, msg), tag: tag, uplevel: uplevel)
end
deprecated_name_message(old, new = nil, msg = nil) click to toggle source

@api private

# File lib/dry/core/deprecations.rb, line 68
        def deprecated_name_message(old, new = nil, msg = nil)
          if new
            deprecation_message(old, <<-MSG)
              Please use #{new} instead.
              #{msg}
            MSG
          else
            deprecation_message(old, msg)
          end
        end
deprecation_message(name, msg) click to toggle source

@api private

# File lib/dry/core/deprecations.rb, line 60
        def deprecation_message(name, msg)
          <<-MSG
            #{name} is deprecated and will be removed in the next major version
            #{msg}
          MSG
        end
logger(output = $stderr) click to toggle source

Returns the logger used for printing warnings. You can provide your own with .set_logger!

@param [IO] output output stream

@return [Logger]

# File lib/dry/core/deprecations.rb, line 85
def logger(output = $stderr)
  if defined?(@logger)
    @logger
  else
    set_logger!(output)
  end
end
set_logger!(output = $stderr) click to toggle source

Sets a custom logger. This is a global setting.

@overload set_logger!(output)

@param [IO] output Stream for messages

@overload set_logger!

Stream messages to stdout

@overload set_logger!(logger)

@param [#warn] logger

@api public

# File lib/dry/core/deprecations.rb, line 105
def set_logger!(output = $stderr) # rubocop:disable Naming/AccessorMethodName
  if output.respond_to?(:warn)
    @logger = output
  else
    @logger = Logger.new(output).tap do |logger|
      logger.formatter = proc { |_, _, _, msg| "#{msg}\n" }
    end
  end
end
warn(msg, tag: nil, uplevel: nil) click to toggle source

Prints a warning

@param [String] msg Warning string @param [String] tag Tag to help identify the source of the warning.

Defaults to "deprecated"

@param [Integer] Caller frame to add to the message

# File lib/dry/core/deprecations.rb, line 39
def warn(msg, tag: nil, uplevel: nil)
  caller_info = uplevel.nil? ? nil : "#{caller_locations(uplevel + 2, 1)[0]} "
  tag = "[#{tag || "deprecated"}] "
  hint = msg.gsub(/^\s+/, "")

  logger.warn("#{caller_info}#{tag}#{hint}")
end