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 



103
104
105
 
# File 'lib/dry/core/deprecations.rb', line 103

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



43
44
45
 
# File 'lib/dry/core/deprecations.rb', line 43

def announce(name, msg, tag: nil)
  warn(deprecation_message(name, msg), tag: tag)
end

.deprecated_method_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. 



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

def deprecated_method_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. 



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

def deprecation_message(name, msg)
  <<-MSG
    #{ name } is deprecated and will be removed in the next major version
    #{ msg }
  MSG
end

.logger(output = nil) ⇒ Logger

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

Parameters:

  • output (IO) (defaults to: nil) —

    output stream

Returns:

  • (Logger) 


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

def logger(output = nil)
  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:



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

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



34
35
36
37
 
# File 'lib/dry/core/deprecations.rb', line 34

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