Module: Dry::Core::Deprecations

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

Overview

An extension for issueing 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_method :old_api, :new_api, "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 



105
106
107
 
# File 'lib/dry/core/deprecations.rb', line 105

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

.announce(name, msg, tag: 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



45
46
47
 
# File 'lib/dry/core/deprecations.rb', line 45

def announce(name, msg, tag: nil)
  warn(deprecation_message(name, msg), tag: tag)
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. 



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/dry/core/deprecations.rb', line 58

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. 



50
51
52
53
54
55
 
# File 'lib/dry/core/deprecations.rb', line 50

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) 


75
76
77
78
79
80
81
 
# File 'lib/dry/core/deprecations.rb', line 75

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:



95
96
97
98
99
100
101
102
103
 
# File 'lib/dry/core/deprecations.rb', line 95

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

.warn(msg, tag: nil) ⇒ Object

Prints a warning

Parameters:

  • msg (String) —

    Warning string



36
37
38
39
 
# File 'lib/dry/core/deprecations.rb', line 36

def warn(msg, tag: nil)
  tagged = "[#{tag || 'deprecated'}] #{msg.gsub(/^\s+/, '')}"
  logger.warn(tagged)
end