module Deprecation

Constants

ACTIVESUPPORT_CONCERN_REGEX
IGNORE_REGEX
VERSION

Attributes

default_deprecation_behavior[RW]
show_full_callstack[RW]

Public Class Methods

behaviors(klass) click to toggle source
# 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) { || ... } click to toggle source
# 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) click to toggle source

Declare that a method has been deprecated.

# 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) click to toggle source
# 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) click to toggle source
# 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() click to toggle source
# File lib/deprecation/behaviors.rb, line 41
def self.deprecations
  @deprecations ||= {}
end
logger() click to toggle source
# 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) click to toggle source
# File lib/deprecation.rb, line 47
def self.logger= value
  @logger = value
end
silence(context) { || ... } click to toggle source

Silence deprecation warnings within the block.

# 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) click to toggle source

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

Private Class Methods

deprecation_caller_message(callstack) click to toggle source
# File lib/deprecation/reporting.rb, line 80
def deprecation_caller_message(callstack)
  if Deprecation.show_full_callstack
    return "(Callstack: #{callstack.join "\n\t"})"
  end
  file, line, method = extract_callstack(callstack)
  if file
    if line && method
      "(called from #{method} at #{file}:#{line})"
    else
      "(called from #{file}:#{line})"
    end
  end
end
deprecation_gem_root() click to toggle source
# File lib/deprecation/reporting.rb, line 109
def deprecation_gem_root
  File.expand_path("../..", __FILE__) + "/"
end
deprecation_message(callstack, message = nil) click to toggle source
# File lib/deprecation/reporting.rb, line 74
def deprecation_message(callstack, message = nil)
  message ||= "You are using deprecated behavior which will be removed from the next major or minor release."
  message += '.' unless message =~ /\.$/
  "DEPRECATION WARNING: #{message} #{deprecation_caller_message(callstack)}"
end
extract_callstack(callstack) click to toggle source
# File lib/deprecation/reporting.rb, line 94
def extract_callstack(callstack)
  offending_line = sanitized_callstack(callstack).first || callstack.first
  if offending_line
    if md = offending_line.match(/^(.+?):(\d+)(?::in `(.*?)')?/)
      md.captures
    else
      offending_line
    end
  end
end
sanitized_callstack(callstack) click to toggle source
# File lib/deprecation/reporting.rb, line 105
def sanitized_callstack(callstack)
  callstack.reject { |line| line.start_with? deprecation_gem_root}.select { |line| (line =~ IGNORE_REGEX).nil? }
end

Public Instance Methods

debug() click to toggle source
# File lib/deprecation.rb, line 29
def debug
  @debug
end
Also aliased as: debug?
debug=(bool) click to toggle source
# File lib/deprecation.rb, line 34
def debug= bool
  @debug = bool
end
debug?()
Alias for: debug
deprecation_behavior() click to toggle source

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

# File lib/deprecation/behaviors.rb, line 13
def deprecation_behavior
  @deprecation_behavior ||= [Deprecation.behaviors(self)[Deprecation.default_deprecation_behavior]]
end
deprecation_behavior=(deprecation_behavior) click to toggle source

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
}
# 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() click to toggle source
# File lib/deprecation.rb, line 15
def deprecation_horizon
  @deprecation_horizon
end
deprecation_horizon=(horizon) click to toggle source
# File lib/deprecation.rb, line 11
def deprecation_horizon= horizon
  @deprecation_horizon = horizon
end
silenced() click to toggle source
# File lib/deprecation.rb, line 19
def silenced
  @silenced
end
Also aliased as: silenced?
silenced=(bool) click to toggle source
# File lib/deprecation.rb, line 25
def silenced= bool
  @silenced = bool
end
silenced?()
Alias for: silenced