module Deprecated

Deprecated is a module to help you deprecate code BEFORE you remove it. Don't surprise your users, deprecate them!

Usage is simple:

class Foo
  include Deprecated

  def moo
    "cow"
  end

  deprecated :moo

  def sheep
    "baaa"
  end

  deprecated :sheep, "Sounds#baa"

  protected

  def bar
    true
  end

  deprecated :bar
end

Foo.new.moo # warns that the call is deprecated

Deprecated.set_action(:raise)
Foo.new.moo # raises with the same message

Deprecated.set_action do |klass, sym, replacement|
  email_boss(
    "Someone tried to use #{klass}##{sym}! " +
    "They should be using #{replacement} instead!"
  )
end

Foo.new.sheep # do I really need to explain?

Foo.new.bar # still protected!

Let's do it live!

class Bar
  include Deprecated

  # sets it just for this class
  deprecated_set_action do |klass, sym, replacement|
    email_boss(
      "Someone tried to use #{klass}##{sym}! " +
      "They should be using #{replacement} instead!"
    )
  end

  def cow
    "moo"
  end

  deprecate :cow # emails your boss when called!
end

Please see Deprecated::Module#deprecated, Deprecated.set_action, and Deprecated::Module#deprecated_set_action for more information.

Constants

VERSION

Public Class Methods

action() click to toggle source

Returns the current action; this may be block or Proc.

# File lib/deprecated.rb, line 138
def self.action
  @action
end

build_message(klass, sym, replacement) click to toggle source

# File lib/deprecated.rb, line 83
def self.build_message(klass, sym, replacement)
  message = "#{klass}##{sym} is deprecated."

  if replacement
    message += " Please use #{replacement}."
  end

  return message
end

included(base) click to toggle source

# File lib/deprecated.rb, line 198
def self.included(base)
  base.extend(Module)
end

run_action(klass, sym, replacement) click to toggle source

Is called when an action needs to be run. Proably not in your best interest to run this directly.

# File lib/deprecated.rb, line 130
def self.run_action(klass, sym, replacement)
  raise "run_action has no associated hook" unless @action
  @action.call(klass, sym, replacement)
end

set_action(type=nil, &block) click to toggle source

set_action takes 3 “canned” arguments or an arbitrary block. If you provide the block, any canned argument is ignored.

The canned arguments are:

:warn: display a warning
:raise: raise a DeprecatedError (a kind of StandardError) with the warning.
:fail: fail. die. kaput. it's over.

Procs take three arguments:

The class of the method
The method name itself, a symbol
A replacement string which may be nil

# File lib/deprecated.rb, line 109
def self.set_action(type=nil, &block)
  @action = if block
              block
            else
              case type
              when :warn
                proc { |*args| warn build_message(*args) }
              when :fail
                proc { |*args| fail build_message(*args) }
              when :raise
                proc { |*args| raise DeprecatedError, build_message(*args) }
              else
                raise ArgumentError, "you must provide a symbol or a block to set_action()."
              end
            end
end

Public Instance Methods

__deprecated_run_action__(sym, replacement) click to toggle source

# File lib/deprecated.rb, line 75
def __deprecated_run_action__(sym, replacement)
  if self.class.instance_eval { @__deprecated_run_action__ }
    self.class.instance_eval { @__deprecated_run_action__ }.call(self.class, sym, replacement) 
  else
    Deprecated.run_action(self.class, sym, replacement)
  end
end