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