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.
Returns the current action; this may be block or Proc.
# File lib/deprecated.rb, line 138 def self.action @action end
# 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
# File lib/deprecated.rb, line 198 def self.included(base) base.extend(Module) end
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 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
# 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
Generated with the Darkfish Rdoc Generator 2.