module Safrano::Deprecation
This module makes it easy to print deprecation warnings with optional backtraces to a given stream. There are a two accessors you can use to change how/where the deprecation methods are printed and whether/how backtraces should be included:
Safrano::Deprecation.output = $stderr # print deprecation messages to standard error (default) Safrano::Deprecation.output = File.open('deprecated_calls.txt', 'wb') # use a file instead Safrano::Deprecation.output = false # do not output deprecation messages Safrano::Deprecation.prefix = "SAFRANO DEPRECATION WARNING: " # prefix deprecation messages with a given string (default) Safrano::Deprecation.prefix = false # do not prefix deprecation messages Safrano::Deprecation.backtrace_filter = false # don't include backtraces Safrano::Deprecation.backtrace_filter = true # include full backtraces Safrano::Deprecation.backtrace_filter = 2 # include 2 backtrace lines (default) Safrano::Deprecation.backtrace_filter = 1 # include 1 backtrace line Safrano::Deprecation.backtrace_filter = lambda{|line, line_no| line_no < 3 || line =~ /my_app/} # select backtrace lines to output
Attributes
How to filter backtraces. false
does not include backtraces, true
includes full backtraces, an Integer includes that number of backtrace lines, and a proc is called with the backtrace line and line number to select the backtrace lines to include. The default is no backtrace .
Where deprecation messages should be output, must respond to puts. $stderr by default.
Where deprecation messages should be prefixed with (“SEQUEL DEPRECATION WARNING: ” by default).
Public Class Methods
Print the message and possibly backtrace to the output.
# File lib/safrano/deprecation.rb, line 42 def self.deprecate(method, instead = nil) return unless output message = instead ? "#{method} is deprecated and will be removed in Safrano 0.6. #{instead}." : method message = "#{prefix}#{message}" if prefix output.puts(message) case b = backtrace_filter when Integer caller.each do |c| b -= 1 output.puts(c) break if b <= 0 end when true caller.each { |c| output.puts(c) } when Proc caller.each_with_index { |line, line_no| output.puts(line) if b.call(line, line_no) } end nil end
If using ruby 2.3+, use Module#deprecate_constant to deprecate the constant, otherwise do nothing as the ruby implementation does not support constant deprecation.
# File lib/safrano/deprecation.rb, line 65 def self.deprecate_constant(mod, constant) # :nocov: return unless RUBY_VERSION > '2.3' # :nocov: mod.deprecate_constant(constant) end