deprecated 1.0.0

data/lib/deprecated.rb

@@ -0,0 +1,226 @@
+#
+# Deprecate - handle deprecating and executing deprecated code
+#
+# Version:: 1.0.0
+# Author:: Erik Hollensbe
+# License:: BSD
+# Copyright:: Copyright (c) 2006 Erik Hollensbe
+# Contact:: erik@hollensbe.org
+#
+# Deprecate is intended to ease the programmer's control over
+# deprecating and handling deprecated code.
+#
+# Usage is simple:
+#
+#   # require 'rubygems' if need be
+#   require 'deprecate'
+#   
+#   class Foo
+#     private
+#       # rename the original function and make it private
+#       def _monkey
+#         do stuff...
+#       end
+#     public
+#     # deprecate the function, this will create a 'monkey' method
+#     # that will call the deprecate warnings
+#     deprecate :monkey, :_monkey
+#   end
+#
+# The 'deprecate' call is injected into the 'Module' class at
+# require-time. This allows all classes that are newly-created to
+# access the 'deprecate' functionality.
+#
+# The call itself takes a list of symbols. Each pair is first the name
+# of the original function, the second the name of the current,
+# renamed function. Both are represented as symbols.
+#
+#   Ex:
+#
+#   # foo subroutine is generated to call _foo, and notify the user
+#   # when called.
+#   deprecate :foo, :_foo
+#
+# You can define as many symbols as you like on one line as
+# deprecated, but for obvious reasons the length of the list must be
+# even. In the case that it isn't, the 'deprecate' call will throw an
+# exception of type 'DeprecatedError'.
+#
+# If you prefer to have more sugar in your syntax, the call
+# understands arrays:
+#
+#   deprecate [:foo, :_foo], [:bar, :_bar]
+#
+# And of course, you can make the call multiple times.
+#
+# 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 leading
+# 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.
+#
+# Deprecate.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.
+#
+#--
+#
+# The compilation of software known as deprecate.rb is distributed under the
+# following terms:
+# Copyright (C) 2005-2006 Erik Hollensbe. All rights reserved.
+#
+# Redistribution and use in source form, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer:
+#
+# THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+# SUCH DAMAGE.
+#
+#++
+
+module Deprecate
+  
+  CALLER_REGEX = /\`([^\']+)/
+  
+  #
+  # set_action defines the action that will be taken when code marked
+  # deprecated is encountered. There are several stock options:
+  #
+  # * :warn -- print a warning message to stderr (default)
+  # * :die  -- warn and then terminate the program with error level -1
+  # * :throw -- throw a DeprecatedError with the message
+  #
+  # If a proc is passed instead, it will execute that instead. This
+  # procedure is passed a single argument, which is the name (NOT the
+  # symbol) of the method in Class#meth syntax that was called. This
+  # does not interrupt the calling process (unless you do so
+  # yourself).
+  #
+  # The second argument is the message provided to warnings and throw
+  # errors and so on. This message is a sprintf-like formatted string
+  # that takes one argument, which is the Class#meth name as a string.
+  # This message is not used when you define your own procedure.
+  # 
+  # Note: ALL code that is marked deprecated will behave in the manner
+  # that was set at the last call to set_action.
+  #
+  # Ex:
+  #
+  #    # throws with the error message saying: "FIXME: Class#meth"
+  #    Deprecate.set_action(:throw, "FIXME: %s")
+  #
+  #    # emails your boss everytime you run deprecated code
+  #    Deprecate.set_action proc do |msg|
+  #       f = IO.popen('mail boss@company -s "Joe still hasn't fixed %s"' % msg, 'w')
+  #       f.puts("Sorry, I still haven't fixed %s, please stop making me go to meetings.\n" % msg)
+  #       f.close
+  #    end
+  #
+  
+  @@action = nil
+  
+  def Deprecate.action
+    return @@action
+  end
+  
+  def Deprecate.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
+end
+
+#
+# This is the class of the errors that the 'Deprecate' module will
+# throw if the action type is set to ':throw'.
+#
+# See Deprecate.set_action for more information.
+#
+class DeprecatedError < Exception
+  attr_reader :message
+  def initialize(msg=nil)
+    @message = msg
+  end
+end
+
+#
+# Start - inject the 'deprecated' method into the 'Module' class and
+# set the default action to warn.
+#
+
+Module.send(:define_method, :deprecate, 
+            proc do |*args|
+              args.flatten!
+              if args.length
+
+                permission = :public
+
+                if args.length % 2 != 0
+                  permission = args.shift
+                end
+
+                while args.length > 0
+                  syms = args.slice! 0, 2
+                  
+                  if syms.include? nil
+                    raise DeprecatedError.new("Invalid number of arguments passed to 'deprecated' function")
+                  end
+                  
+                  define_method(syms[0]) do |*sendparams|
+                    Deprecate.action.call(self.class.to_s + '#' + syms[0].to_s)
+                    self.send(syms[1], *sendparams) 
+                  end
+                  
+                  case permission
+                  when :public
+                    public(syms[0])
+                  when :protected
+                    protected(syms[0])
+                  when :private
+                    private(syms[0])
+                  end
+
+                end
+              end
+            end)
+
+Deprecate.set_action(:warn)

data/test/deprecated.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+
+require 'lib/deprecate.rb'
+require 'test/unit'
+
+# this class is used to test the deprecate functionality
+class DummyClass
+  deprecate :monkey, :_monkey
+
+  def _monkey
+    return true
+  end
+
+end
+
+# we want exceptions for testing here.
+Deprecate.set_action(:throw)
+
+class DeprecateTest < Test::Unit::TestCase
+  def set_action_builder
+    d = DummyClass.new
+    test = true
+    begin
+      d.monkey
+      test = false
+    rescue DeprecatedError => e
+      test = e.message == "DummyClass#monkey is deprecated."
+    end
+
+    return test
+  end
+
+  # this inadvertently tests the deprecate functionality as well...
+  def test_set_action
+     
+    assert(set_action_builder, "Deprecate.set_action message/:throw test")
+
+    Deprecate.set_action(proc { |msg| raise DeprecatedError.new("#{msg} is deprecated.") })
+
+    assert(set_action_builder, "Deprecate.set_action custom proc test")
+  end
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: deprecated
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2006-02-15 00:00:00 -08:00
+summary: An easy way to handle deprecating and conditionally running deprecated code
+require_paths: 
+- lib
+email: erik@hollensbe.org
+homepage: 
+rubyforge_project: deprecated
+description: 
+autorequire: deprecated
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Erik Hollensbe
+files: 
+- lib/deprecated.rb
+- test/deprecated.rb
+test_files: 
+- test/deprecated.rb
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+