Module: Deprecation

Extended by:
ActiveSupport::Concern
Defined in:
lib/deprecation.rb,
lib/deprecation/rspec.rb,
lib/deprecation/version.rb,
lib/deprecation/behaviors.rb,
lib/deprecation/reporting.rb,
lib/deprecation/method_wrappers.rb

Defined Under Namespace

Classes: RSpec

Constant Summary collapse

VERSION = 
"1.1.0"
ACTIVESUPPORT_CONCERN_REGEX = 
%r{/lib/active_support/concern.rb}
IGNORE_REGEX = 
Regexp.union(ACTIVESUPPORT_CONCERN_REGEX)

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.default_deprecation_behavior ⇒ Object

Returns the value of attribute default_deprecation_behavior.



7
8
9
 
# File 'lib/deprecation/behaviors.rb', line 7

def default_deprecation_behavior
  @default_deprecation_behavior
end

.show_full_callstack ⇒ Object

Returns the value of attribute show_full_callstack.



7
8
9
 
# File 'lib/deprecation/reporting.rb', line 7

def show_full_callstack
  @show_full_callstack
end

Class Method Details

.behaviors(klass) ⇒ Object 



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/deprecation/behaviors.rb', line 45

def self.behaviors klass
  # Default warning behaviors per Rails.env.
  {
:stderr => Proc.new { |message, callstack|
   $stderr.puts(message)
   $stderr.puts callstack.join("\n  ") if klass.respond_to? :debug and klass.debug
 },
:log => Proc.new { |message, callstack|
   logger = Deprecation.logger
   logger.warn message
   logger.debug callstack.join("\n  ") if klass.respond_to? :debug and klass.debug
 },
 :notify => Proc.new { |message, callstack|
    ActiveSupport::Notifications.instrument("deprecation.#{klass.to_s}",
    :message => message, :callstack => callstack)
 },
 :raise => Proc.new { |message, callstack| raise message },
 :silence => Proc.new { |message, callstack| },
 :test => Proc.new do |message, callstack| 
    hash = message.hash + callstack[0..2].join("\n").hash
    unless self.deprecations[hash]
      self.deprecations[hash] = { message: message, callstack: callstack, count: 1 }
    else
      self.deprecations[hash][:count] += 1
    end
  end,
 :stderr_report => Proc.new do |message, callstack|
    hash = message.hash + callstack[0..2].join("\n").hash
    unless self.deprecations[hash]
      self.deprecations[hash] = { message: message, callstack: callstack, count: 1 }
      $stderr.puts(message)
      $stderr.puts callstack.join("\n  ") if klass.respond_to? :debug and klass.debug
    else
      self.deprecations[hash][:count] += 1
    end
  end
  }
end

.collect(context) ⇒ Object 



44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/deprecation/reporting.rb', line 44

def collect(context)
  old_behavior = context.deprecation_behavior
  deprecations = []
  context.deprecation_behavior = Proc.new do |message, callstack|
    deprecations << message
  end
  result = yield
  [result, deprecations]
ensure
  context.deprecation_behavior = old_behavior
end

.deprecate_methods(target_module, *method_names) ⇒ Object

Declare that a method has been deprecated.



6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/deprecation/method_wrappers.rb', line 6

def self.deprecate_methods(target_module, *method_names)
  options = method_names.extract_options!
  method_names += options.keys

  generated_deprecation_methods = Module.new
  method_names.each do |method_name|
    if RUBY_VERSION < '3'
      generated_deprecation_methods.module_eval(<<-end_eval, __FILE__, __LINE__ + 1)
        def #{method_name}(*args, &block)
          Deprecation.warn(#{target_module.to_s},
            Deprecation.deprecated_method_warning(#{target_module.to_s},
              :#{method_name},
              #{options[method_name].inspect}),
            caller
          )
          super
        end
        pass_keywords(:#{method_name}) if respond_to?(:pass_keywords, true)
      end_eval
    else
      generated_deprecation_methods.module_eval(<<-end_eval, __FILE__, __LINE__ + 1)
        def #{method_name}(*args, **kwargs, &block)
          Deprecation.warn(#{target_module.to_s},
            Deprecation.deprecated_method_warning(#{target_module.to_s},
              :#{method_name},
              #{options[method_name].inspect}),
            caller
          )
          super
        end
      end_eval
    end
  end
  target_module.prepend generated_deprecation_methods
end

.deprecated_method_warning(context, method_name, options = nil) ⇒ Object 



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/deprecation/reporting.rb', line 56

def deprecated_method_warning(context, method_name, options = nil)

  options ||= {}

  if options.is_a? String  or options.is_a? Symbol
    message = options
    options = {}
  end

  warning = "#{method_name} is deprecated and will be removed from #{options[:deprecation_horizon] || (context.deprecation_horizon if context.respond_to? :deprecation_horizon) || "a future release"}"
  case message
    when Symbol then "#{warning} (use #{message} instead)"
    when String then "#{warning} (#{message})"
    else warning
  end
end

.deprecation_behavior(context) ⇒ Object 



25
26
27
28
29
30
31
 
# File 'lib/deprecation/reporting.rb', line 25

def deprecation_behavior context
  if context.respond_to? :deprecation_behavior
    context.deprecation_behavior 
  else
    [Deprecation.behaviors(self)[Deprecation.default_deprecation_behavior]]
  end
end

.deprecations ⇒ Object 



41
42
43
 
# File 'lib/deprecation/behaviors.rb', line 41

def self.deprecations
  @deprecations ||= {}
end

.logger ⇒ Object 



38
39
40
41
42
43
44
45
 
# File 'lib/deprecation.rb', line 38

def self.logger
  @logger ||= if defined?(Rails) && Rails.logger
    Rails.logger
  else
    require 'active_support/logger'
    ActiveSupport::Logger.new($stderr)
  end
end

.logger=(value) ⇒ Object 



47
48
49
 
# File 'lib/deprecation.rb', line 47

def self.logger= value
  @logger = value
end

.silence(context) ⇒ Object

Silence deprecation warnings within the block.



34
35
36
37
38
39
40
41
42
 
# File 'lib/deprecation/reporting.rb', line 34

def silence context
  if context.respond_to? :silenced=
    old_silenced, context.silenced = context.silenced, true
  end

  yield
ensure
  context.silenced = old_silenced if context.respond_to? :silenced=
end

.warn(context, message = nil, callstack = nil) ⇒ Object

Outputs a deprecation warning to the output configured by ActiveSupport::Deprecation.behavior

Deprecation.warn("something broke!")
# => "DEPRECATION WARNING: something broke! (called from your_code.rb:1)"



12
13
14
15
16
17
18
19
20
21
22
23
 
# File 'lib/deprecation/reporting.rb', line 12

def warn(context, message = nil, callstack = nil)
  return if context.respond_to? :silenced? and context.silenced?

  if callstack.nil?
    callstack = caller
    callstack.shift
  end

  deprecation_message(callstack, message).tap do |m|
    deprecation_behavior(context).each { |b| b.call(m, sanitized_callstack(callstack)) }
  end
end

Instance Method Details

#debug ⇒ Object Also known as: debug? 



29
30
31
 
# File 'lib/deprecation.rb', line 29

def debug
  @debug
end

#debug=(bool) ⇒ Object 



34
35
36
 
# File 'lib/deprecation.rb', line 34

def debug= bool
  @debug = bool
end

#deprecation_behavior ⇒ Object

Returns the current behavior or if one isn’t set, defaults to :stderr



13
14
15
 
# File 'lib/deprecation/behaviors.rb', line 13

def deprecation_behavior
  @deprecation_behavior ||= [Deprecation.behaviors(self)[Deprecation.default_deprecation_behavior]]
end

#deprecation_behavior=(deprecation_behavior) ⇒ Object

Sets the behavior to the specified value. Can be a single value, array, or an object that responds to call.

Available behaviors:

stderr

Log all deprecation warnings to $stderr.

log

Log all deprecation warnings to Rails.logger.

+notify

Use ActiveSupport::Notifications to notify deprecation.rails.

silence

Do nothing.

Setting behaviors only affects deprecations that happen after boot time. Deprecation warnings raised by gems are not affected by this setting because they happen before Rails boots up.

Deprecation.deprecation_behavior = :stderr
Deprecation.deprecation_behavior = [:stderr, :log]
Deprecation.deprecation_behavior = MyCustomHandler
Deprecation.deprecation_behavior = proc { |message, callstack| 
  # custom stuff
}



37
38
39
 
# File 'lib/deprecation/behaviors.rb', line 37

def deprecation_behavior=(deprecation_behavior)
  @deprecation_behavior = Array(deprecation_behavior).map { |b| Deprecation.behaviors(self)[b] || b }
end

#deprecation_horizon ⇒ Object 



15
16
17
 
# File 'lib/deprecation.rb', line 15

def deprecation_horizon
  @deprecation_horizon
end

#deprecation_horizon=(horizon) ⇒ Object 



11
12
13
 
# File 'lib/deprecation.rb', line 11

def deprecation_horizon= horizon
  @deprecation_horizon = horizon
end

#silenced ⇒ Object Also known as: silenced? 



19
20
21
 
# File 'lib/deprecation.rb', line 19

def silenced
  @silenced
end

#silenced=(bool) ⇒ Object 



25
26
27
 
# File 'lib/deprecation.rb', line 25

def silenced= bool
  @silenced = bool
end