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
# File lib/dry/core/deprecations.rb, line 115 def [](tag) Tagged.new(tag) end
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
@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
@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
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
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
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