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 112 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 52 def announce(name, msg, tag: nil, uplevel: nil) warn(deprecation_message(name, msg), tag: tag, uplevel: uplevel) end
@api private
# File lib/dry/core/deprecations.rb, line 65 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 57 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 82 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 102 def set_logger!(output = $stderr) 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[uplevel] tag = "[#{tag || "deprecated"}]" hint = msg.gsub(/^\s+/, "") logger.warn( [caller_info, tag, hint].compact.join(" ") ) end