Module: Sequel::Deprecation

Defined in:
lib/sequel/deprecated.rb

Overview

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:

Sequel::Deprecation.output = $stderr # print deprecation messages to standard error (default)
Sequel::Deprecation.output = File.open('deprecated_calls.txt', 'wb') # use a file instead
Sequel::Deprecation.output = false # do not output deprecation messages

Sequel::Deprecation.prefix = "SEQUEL DEPRECATION WARNING: " # prefix deprecation messages with a given string (default)
Sequel::Deprecation.prefix = false # do not prefix deprecation messages

Sequel::Deprecation.backtrace_filter = false # don't include backtraces
Sequel::Deprecation.backtrace_filter = true # include full backtraces
Sequel::Deprecation.backtrace_filter = 10 # include 10 backtrace lines (default)
Sequel::Deprecation.backtrace_filter = 1 # include 1 backtrace line
Sequel::Deprecation.backtrace_filter = lambda{|line, line_no| line_no < 3 || line =~ /my_app/} # select backtrace lines to output

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.backtrace_filter ⇒ Object

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 10 backtrace lines.



28
29
30
 
# File 'lib/sequel/deprecated.rb', line 28

def backtrace_filter
  @backtrace_filter
end

.output ⇒ Object

Where deprecation messages should be output, must respond to puts. $stderr by default.



31
32
33
 
# File 'lib/sequel/deprecated.rb', line 31

def output
  @output
end

.prefix ⇒ Object

Where deprecation messages should be prefixed with (“SEQUEL DEPRECATION WARNING: ” by default).



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

def prefix
  @prefix
end

Class Method Details

.deprecate(method, instead = nil) ⇒ Object

Print the message and possibly backtrace to the output.



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/sequel/deprecated.rb', line 38

def self.deprecate(method, instead=nil)
  return unless output
  message = instead ? "#{method} is deprecated and will be removed in Sequel 4.0.  #{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

.deprecated_module(mod, &block) ⇒ Object

Return a module that includes deprecation warnings for all public instance methods in the given module, such that including the returned module will not result in the given module being included.



61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/sequel/deprecated.rb', line 61

def self.deprecated_module(mod, &block)
  Module.new do
    include mod.dup
    mod.public_instance_methods.each do |meth|
      msg = block.call(meth)
      define_method(meth) do |*a, &blk|
        Sequel::Deprecation.deprecate(*msg)
        super(*a, &blk)
      end
    end
  end
end