deprecated 2.0.1 → 3.0.0

data/Rakefile

@@ -0,0 +1,81 @@
+#
+# Please see the COPYING file in the source distribution for copyright information.
+# 
+
+begin
+    require 'rubygems'
+    gem 'test-unit'
+rescue LoadError
+end
+
+$:.unshift 'lib'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rdoc/task'
+require 'deprecated'
+
+task :default => [ :dist ]
+
+#
+# Tests
+#
+
+Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.test_files = FileList['test/test*.rb']
+    t.verbose = true 
+end
+
+#
+# Distribution
+#
+
+task :dist      => [:test, :repackage, :gem, :rdoc]
+task :distclean => [:clobber_package, :clobber_rdoc]
+task :clean     => [:distclean]
+
+task :to_blog => [:clobber_rdoc, :rdoc] do
+    sh "rm -r $git/blog/content/docs/deprecated && mv rdoc $git/blog/content/docs/deprecated"
+end
+
+
+#
+# Documentation
+#
+
+RDoc::Task.new do |rd|
+    rd.rdoc_dir = "rdoc"
+    rd.main = "README"
+    rd.rdoc_files.include("README")
+    rd.rdoc_files.include("./lib/**/*.rb")
+    rd.options = %w(-a)
+end
+
+#
+# Packaging
+# 
+
+spec = Gem::Specification.new do |s|
+    s.name = "deprecated"
+    s.version = Deprecated::VERSION
+    s.author = "Erik Hollensbe"
+    s.email = "erik@hollensbe.org"
+    s.summary = "An easy way to handle deprecating and conditionally running deprecated code"
+    s.has_rdoc = true
+    s.files = Dir['Rakefile'] + Dir['lib/deprecated.rb'] + Dir['test/test_deprecated.rb']
+    s.test_file = "test/test_deprecated.rb"
+    s.rubyforge_project = 'deprecated'
+end
+
+Rake::GemPackageTask.new(spec) do |s|
+end
+
+Rake::PackageTask.new(spec.name, spec.version) do |p|
+    p.need_tar_gz = true
+    p.need_zip = true
+    p.package_files.include("./setup.rb")
+    p.package_files.include("./Rakefile")
+    p.package_files.include("./lib/**/*.rb")
+    p.package_files.include("./test/**/*")
+end

data/lib/deprecated.rb

@@ -1,199 +1,203 @@
+class DeprecatedError < StandardError; end
+
 #
-# Deprecated - handle deprecating and executing deprecated code
+# Deprecated is a module to help you deprecate code BEFORE you remove it. Don't
+# surprise your users, deprecate them!
 #
-# Version:: 2.0.1
-# Author:: Erik Hollensbe
-# License:: BSD
-# Copyright:: Copyright (c) 2006 Erik Hollensbe
-# Contact:: erik@hollensbe.org
+# Usage is simple:
 #
-# Deprecated is intended to ease the programmer's control over
-# deprecating and handling deprecated code.
+#     class Foo
+#       include Deprecated
 #
-# Usage is simple:
+#       def moo
+#         "cow"
+#       end
+#
+#       deprecated :moo
+#
+#       def sheep
+#         "baaa"
+#       end
+#
+#       deprecated :sheep, "Sounds#baa"
 #
-#   # require 'rubygems' if need be
-#   require 'deprecated'
-#   
-#   class Foo
-#     private
-#     # rename the original function and make it private
-#     def monkey
-#       do stuff...
+#       protected
+#
+#       def bar
+#         true
+#       end
+#
+#       deprecated :bar
 #     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.
-#
-#--
-#
-# 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.
-#
-#++
-
+#     
+#     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.
+#
 module Deprecated
-  
-  #
-  # 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"
-  #    Deprecated.set_action(:throw, "FIXME: %s")
-  #
-  #    # emails your boss everytime you run deprecated code
-  #    Deprecated.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 Deprecated.action
-    return @@action
-  end
-  
-  def Deprecated.set_action(action, message="%s is deprecated.")
-    if action.kind_of? Proc
-      @@action = action
-      return
+    VERSION = "3.0.0"
+
+    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
-    
-    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
+
+    def self.build_message(klass, sym, replacement)
+        message = "#{klass}##{sym} is deprecated."
+
+        if replacement
+            message += " Please use #{replacement}."
+        end
+
+        return message
     end
-  end
-end
 
-#
-# This is the class of the errors that the 'Deprecated' module will
-# throw if the action type is set to ':throw'.
-#
-# See Deprecated.set_action for more information.
-#
-class DeprecatedError < Exception
-  attr_reader :message
-  def initialize(msg=nil)
-    @message = msg
-  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
+    #
+    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
+
+    # 
+    # Is called when an action needs to be run. Proably not in your best
+    # interest to run this directly.
+    #
+    def self.run_action(klass, sym, replacement)
+        raise "run_action has no associated hook" unless @action
+        @action.call(klass, sym, replacement)
+    end
+
+    #
+    # Returns the current action; this may be block or Proc.
+    #
+    def self.action
+        @action
+    end
 end
 
-#
-# Start - inject the 'deprecated' method into the 'Module' class and
-# set the default action to warn.
-#
+module Deprecated
+    module Module
+
+        #
+        # deprecated takes up to three arguments:
+        #
+        # - A symbol which is the name of the method you wish to deprecate
+        #   (required)
+        # - A string or symbol which is the replacement method. If you provide
+        #   this, your users will be instructed to use that method instead.
+        # - A symbol of :public, :private, or :protected which determines the
+        #   new scope of the method. If you do not provide one, it will be
+        #   searched for in the various collections, and scope will be chosen
+        #   that way.
+        # 
+        def deprecated(sym, replacement=nil, scope=nil)
+            unless sym.kind_of?(Symbol)
+                raise ArgumentError, "deprecated() requires symbols for its first argument." 
+            end
 
-Module.send(:define_method, :deprecate, 
-            proc do |*args|
-              sym = args.shift
-              protection = args.shift || :public
-              
-              unless sym
-                raise DeprecatedError.new("Invalid number of arguments passed to 'deprecated' function")
-              end
-             
-              old_method = self.instance_method(sym)
-              
-              define_method(sym) do |*sendparams|
-                Deprecated.action.call(self.class.to_s + '#' + sym.to_s)
-                new_method = self.class.instance_method(sym)
-                retval = old_method.bind(self).call(*sendparams)
-                new_method.bind(self)
+            meth = instance_method(sym)
+            unless scope
+                pub = public_instance_methods
+                pro = protected_instance_methods
+                pri = private_instance_methods
+                if pub.include?(sym) or pub.include?(sym.to_s)
+                    scope = :public
+                elsif pro.include?(sym) or pro.include?(sym.to_s)
+                    scope = :protected
+                elsif pri.include?(sym) or pri.include?(sym.to_s)
+                    scope = :private
+                end
+            end
+
+            define_method(sym) do |*args|
+                dep_meth = method(sym).unbind
+                __deprecated_run_action__(sym, replacement)
+                retval = meth.bind(self).call(*args) 
+                dep_meth.bind(self)
                 return retval
-              end
-              
-              case protection
-              when :public
-                public(sym)
-              when :private
-                private(sym)
-              when :protected
-                protected(sym)
-              end
-              
-            end)
+            end
 
-Deprecated.set_action(:warn)
+            method(scope).call(sym) if scope
+            return scope
+        end
 
-Deprecate = Deprecated
+        #
+        # Deprecated.set_action for class scope. See Deprecated.set_action.
+        #
+        def deprecated_set_action(&block)
+            raise "You must provide a block" unless block
+            @__deprecated_run_action__ = block
+        end
+    end
+    
+    def self.included(base)
+        base.extend(Module)
+    end
+end
+
+Deprecated.set_action(:warn)

data/test/test_deprecated.rb

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+gem 'test-unit'
+require 'test/unit'
+require 'lib/deprecated.rb'
+
+# this class is used to test the deprecate functionality
+class DummyClass
+    include Deprecated
+
+    def monkey
+        return true
+    end
+
+    def monkey_bars
+        return true
+    end
+
+    deprecated :monkey
+    deprecated :monkey_bars, "FooClass#fart"
+
+    protected
+
+    def my_protected 
+        return true
+    end
+
+    deprecated :my_protected
+
+    private
+
+    def my_private
+        return true
+    end
+
+    deprecated :my_private
+end
+
+class DummyClass2
+    include Deprecated
+
+    deprecated_set_action do |klass, sym, replacement|
+        raise DeprecatedError, "foo!"
+    end
+
+    def monkey
+        return true
+    end
+
+    deprecated :monkey
+end
+
+# we want exceptions for testing here.
+Deprecated.set_action(:raise)
+
+class DeprecateTest < Test::Unit::TestCase
+    def test_set_action
+        assert_raises(DeprecatedError) { DummyClass.new.monkey }
+
+        Deprecated.set_action { |klass, sym| raise DeprecatedError.new("#{klass}##{sym} is deprecated.") }
+        assert_raises(DeprecatedError.new("DummyClass#monkey is deprecated.")) do 
+            DummyClass.new.monkey 
+        end
+
+        Deprecated.set_action(:raise)
+
+        assert_raises(DeprecatedError.new("DummyClass#monkey is deprecated.")) do 
+            DummyClass.new.monkey 
+        end
+
+        # set to warn and make sure our return values are getting through.
+        Deprecated.set_action(:warn)
+        assert(DummyClass.new.monkey)
+
+        Kernel.module_eval { 
+            def self.fail
+                raise "failed"
+            end
+        }
+        
+        Deprecated.set_action(:fail)
+
+        assert_raises("failed") { DummyClass.new.monkey }
+    end
+
+    def test_scope
+        assert(
+            DummyClass.public_instance_methods.include?(:monkey) ||
+            DummyClass.public_instance_methods.include?("monkey")
+        )
+        assert(
+            DummyClass.protected_instance_methods.include?(:my_protected) ||
+            DummyClass.protected_instance_methods.include?("my_protected")
+        )
+        assert(
+            DummyClass.private_instance_methods.include?(:my_private) ||
+            DummyClass.private_instance_methods.include?("my_private")
+        )
+    end
+
+    def test_scoped_actions
+        assert_raises(DeprecatedError.new("foo!")) { DummyClass2.new.monkey }
+    end
+
+    def test_replacement
+        Deprecated.set_action(:raise)
+
+        assert_raises(DeprecatedError.new("DummyClass#monkey_bars is deprecated. Please use FooClass#fart.")) do 
+            DummyClass.new.monkey_bars
+        end
+    end
+end

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: deprecated
 version: !ruby/object:Gem::Version 
-  version: 2.0.1
+  prerelease: false
+  segments: 
+  - 3
+  - 0
+  - 0
+  version: 3.0.0
 platform: ruby
 authors: 
 - Erik Hollensbe
@@ -9,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-26 00:00:00 -07:00
+date: 2010-05-05 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -22,10 +27,13 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- Rakefile
 - lib/deprecated.rb
-- test/deprecated.rb
+- test/test_deprecated.rb
 has_rdoc: true
 homepage: 
+licenses: []
+
 post_install_message: 
 rdoc_options: []
 
@@ -35,20 +43,22 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: deprecated
-rubygems_version: 1.1.1
+rubygems_version: 1.3.6
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: An easy way to handle deprecating and conditionally running deprecated code
 test_files: 
-- test/deprecated.rb
+- test/test_deprecated.rb

data/test/deprecated.rb

@@ -1,33 +0,0 @@
-#!/usr/bin/env ruby
-
-require 'lib/deprecated.rb'
-require 'test/unit'
-
-# this class is used to test the deprecate functionality
-class DummyClass
-  def monkey
-    return true
-  end
-
-  deprecate :monkey
-end
-
-# we want exceptions for testing here.
-Deprecate.set_action(:throw)
-
-class DeprecateTest < Test::Unit::TestCase
-  def test_set_action
-     
-    assert_raise(DeprecatedError) { raise StandardError.new unless DummyClass.new.monkey }
-
-    Deprecate.set_action(proc { |msg| raise DeprecatedError.new("#{msg} is deprecated.") })
-
-    assert_raise(DeprecatedError) { raise StandardError.new unless DummyClass.new.monkey }
-   
-
-    # set to warn and make sure our return values are getting through.
-    Deprecate.set_action(:warn)
-    
-    assert_nothing_raised(DeprecatedError) { raise StandardError.new unless DummyClass.new.monkey } 
-  end
-end