Module: Dry::Core::Deprecations

Defined in:
lib/dry/core/deprecations.rb

Overview

An extension for issuing warnings on using deprecated methods.

Examples:


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

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")

Defined Under Namespace

Modules: Interface Classes: Tagged

Constant Summary collapse

STACK = 
-> { caller.find { |l| l !~ %r{(lib/dry/core)|(gems)} } }

Class Method Summary collapse

Class Method Details

.[](tag) ⇒ Object 



115
116
117
 
# File 'lib/dry/core/deprecations.rb', line 115

def [](tag)
  Tagged.new(tag)
end

.announce(name, msg, tag: nil, uplevel: nil) ⇒ Object

Wraps arguments with a standard message format and prints a warning

Parameters:

  • name (Object) —

    what is deprecated

  • msg (String) —

    additional message usually containing upgrade instructions



51
52
53
54
55
56
57
 
# 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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



68
69
70
71
72
73
74
75
76
77
 
# 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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



60
61
62
63
64
65
 
# 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) ⇒ Logger

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

Parameters:

  • output (IO) (defaults to: $stderr) —

    output stream

Returns:

  • (Logger) 


85
86
87
88
89
90
91
 
# 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) ⇒ Object .set_logger! ⇒ Object .set_logger!(logger) ⇒ Object

Sets a custom logger. This is a global setting.

Overloads:

  • .set_logger!(output) ⇒ Object

    Parameters:

    • output (IO) —

      Stream for messages

  • .set_logger! ⇒ Object

    Stream messages to stdout

  • .set_logger!(logger) ⇒ Object

    Parameters:



105
106
107
108
109
110
111
112
113
 
# 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) ⇒ Object

Prints a warning

Parameters:

  • msg (String) —

    Warning string

  • tag (String) (defaults to: nil) —

    Tag to help identify the source of the warning. Defaults to “deprecated”

  • Caller (Integer) —

    frame to add to the message



39
40
41
42
43
44
45
 
# 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