module Deprecate

Deprecated - handle deprecating and executing deprecated code

Version: 2.0.1
Author: Erik Hollensbe
License: BSD
Copyright: Copyright © 2006 Erik Hollensbe
Contact: erik@hollensbe.org

Deprecated is intended to ease the programmer's control over deprecating and handling deprecated code.

Usage is simple:

# require 'rubygems' if need be
require 'deprecated'

class Foo
  private
  # rename the original function and make it private
  def monkey
    do stuff...
  end
  # deprecate the function, this will create a 'monkey' method
  # that will call the deprecate warnings
  deprecate :monkey, :private
end

The 'deprecated' call is injected into the 'Module' class at require-time. This allows all classes that are newly-created to access the 'deprecate' functionality. The deprecate definition must follow the method definition. You may only define one deprecated function per call.

Methods deprecated default to 'public'. This is due to a limitation in how Ruby handles permission definition. If you're aware of a workaround to this problem, please let me know.

You can however change this by providing an optional trailing parameter to the 'deprecate' call:

:public - set the created method to be public
:protected - set the created method to be protected
:private - set the created method to be private

Note: It's highly recommended that you make your original methods private so that they cannot be accessed by outside code.

Deprecated.set_action can change the default action (which is a warning printed to stderr) if you prefer. This is ideal for code sweeps where deprecated calls have to be removed. Please see the documentation for this method to get an idea of the options that are available.

Public Class Methods

action() click to toggle source

# File lib/deprecated.rb, line 121
def Deprecated.action
  return @@action
end

set_action(action, message="%s is deprecated.") click to toggle source

# File lib/deprecated.rb, line 125
def Deprecated.set_action(action, message="%s is deprecated.")
  if action.kind_of? Proc
    @@action = action
    return
  end
  
  case action
  when :warn
    @@action = proc do |msg|
      warn(message % msg)
    end
  when :die
    @@action = proc do |msg|
      warn(message % msg)
      exit(-1)
    end
  when :throw
    @@action = proc do |msg| 
      raise DeprecatedError.new(message % msg)
    end
  end
end