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

Class Method Summary collapse

Class Method Details

.[](tag) ⇒ Object 



96
97
98
 
# File 'lib/dry/core/deprecations.rb', line 96

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



41
42
43
 
# File 'lib/dry/core/deprecations.rb', line 41

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. 



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

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. 



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

def deprecation_message(name, msg)
  <<-MSG
    #{name} is deprecated and will be removed in the next major version
    #{message(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) 


79
80
81
82
83
84
85
 
# File 'lib/dry/core/deprecations.rb', line 79

def logger(output = nil)
  if defined?(@logger)
    @logger
  else
    set_logger!(output)
  end
end

.message(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. 



66
67
68
69
70
71
 
# File 'lib/dry/core/deprecations.rb', line 66

def message(msg)
  <<-MSG
    #{msg}
    #{caller.detect { |l| l !~ %r{(lib/dry/core)|(gems)} }}
  MSG
end

.set_logger!(output = nil) ⇒ Object

Sets a custom logger. This is a global settings.

Parameters:

  • [IO] (Hash) —

    a customizable set of options



90
91
92
93
94
 
# File 'lib/dry/core/deprecations.rb', line 90

def set_logger!(output = nil)
  @logger = Logger.new(output || $stdout)
  @logger.formatter = proc { |_severity, _datetime, _progname, msg| "#{msg}\n" }
  @logger
end

.warn(msg, tag: nil) ⇒ Object

Prints a warning

Parameters:

  • msg (String) —

    Warning string



32
33
34
35
 
# File 'lib/dry/core/deprecations.rb', line 32

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