deprecatable 1.0.0

data/lib/deprecatable/deprecated_method.rb

@@ -0,0 +1,210 @@
+require 'deprecatable/util'
+require 'deprecatable/call_site'
+module Deprecatable
+  # DeprecatedMethod holds all the information about a method that was marked
+  # as 'deprecated' through the Deprecatable Module. The Class, method name,
+  # and the file and line number of the deprecated method are stored in
+  # DeprecatedMethod.
+  #
+  # It also is the location in which the calls to the deprected method are
+  # stored. Each call to the deprecated method ends up with a call to
+  # 'log_invocation'. The 'log_invocation' method records the CallSite of
+  # where the deprecated method was called, and the number of times that the
+  # deprecated method was called from that CallSite.
+  #
+  # In general, the first time a deprecated method is called from a particular
+  # CallSite, the Alerter is invoked to report the invocation. All subsequent
+  # calls to the deprecated method do not alert, although the invocation count
+  # is increased. This behavior may be altered through the Deprecatable::Options
+  # instance at Deprecatable.options.
+  #
+  class DeprecatedMethod
+    include Util
+
+    # Public: The Ruby class that has the method being deprecated.
+    #
+    # Returns the Class whos method is being deprecated.
+    attr_reader :klass
+
+    # Public: The method in the klass being deprecated.
+    #
+    # Returns the Symbol of the method being deprecated.
+    attr_reader :method
+
+    # Public: The filesystem path of the file where the deprecation took place.
+    #
+    # Returns the String path to the file.
+    attr_reader :file
+
+    # Public: The line number in the file where hte deprecation took place. This
+    # is a 1 indexed value.
+    #
+    # Returns the Integer line number.
+    attr_reader :line_number
+
+    # Public: The additional message to output with the alerts and reports.
+    #
+    # Returns the String message.
+    attr_reader :message
+
+    # Public: The date on which the deprecate method will be removed.
+    #
+    # Returns the removal date.
+    attr_reader :removal_date
+
+    # Public: The version of the software which will no longer have the
+    # deprecated method.
+    #
+    # Returns the version number.
+    attr_reader :removal_version
+
+    # The aliased name of the method being deprecated. This is what is called by
+    # the wrapper to invoke the original deprecated method.
+    #
+    # Returns the String method name.
+    attr_reader :deprecated_method_name
+
+    # Create a new DeprecatedMethod.
+    #
+    # klass       - The Class containing the deprecated method.
+    # method      - The Symbol method name of the deprecated method.
+    # file        - The String filesystem path where the deprecation took place.
+    # line_number - The Integer line in the file where hte deprecation took 
+    #               place.
+    # options     - The Hash optional parameters (default: {})
+    #               :message         - A String to output along with the rest of
+    #                                  the notifcations about the deprecated
+    #                                  method.
+    #               :removal_date    - The date on which the deprecated method
+    #                                  will be removed.
+    #               :removal_version - The version on which the deprecated 
+    #                                  method will be removed.
+    def initialize( klass, method, file, line_number, options = {} )
+      @klass                  = klass
+      @method                 = method
+      @file                   = File.expand_path( file )
+      @line_number            = Float(line_number).to_i
+      @deprecated_method_name = "_deprecated_#{method}"
+      @invocations            = 0
+      @call_sites             = Hash.new
+      @message                = options[:message]
+      @removal_date           = options[:removal_date]
+      @removal_version        = options[:removal_version]
+      @to_s                   = nil
+      insert_shim( self )
+    end
+
+    # Format the DeprecatedMethod as a String.
+    #
+    # Returns the DeprecatedMethod as a String.
+    def to_s
+      unless @to_s then
+        target = @klass.kind_of?( Class ) ? "#{@klass.name}#" : "#{@klass.name}."
+        @to_s = "#{target}#{@method} defined at #{@file}:#{@line_number}"
+      end
+      return @to_s
+    end
+
+    # Log the invocation of the DeprecatedMethod at the given CallSite. Alert
+    # the media.
+    #
+    # file        - The String path to the file in which the DeprecatedMethod
+    #               was invoked.
+    # line_number - The Integer line_number in the file on which the
+    #               DeprecatedMethod was invoked.
+    #
+    # Returns nothing.
+    def log_invocation( file, line_number )
+      call_site = call_site_for( file, line_number )
+      call_site.increment_invocation_count
+      alert( call_site )
+    end
+
+    # Tell the Deprecatable.alerter to alert if the number of invocations at the
+    # CallSite is less than or equal to the alert frequency.
+    #
+    # call_site - The CallSite instance representing where this DeprecatedMethod
+    #             was invoked.
+    #
+    # Returns nothing.
+    def alert( call_site )
+      if call_site.invocation_count <= ::Deprecatable.options.alert_frequency then
+        ::Deprecatable.alerter.alert( self, call_site )
+      end
+    end
+
+    # Gets the lines of all the CallSites where this DeprecatedMethod was
+    # invoked.
+    #
+    # Returns an Array of CallSite instances.
+    def call_sites
+      @call_sites.values
+    end
+
+    # Gets the sum total of all the invocations of this DeprecatedMethod.
+    #
+    # Returns the Integer count of invocations.
+    def invocation_count
+      sum = 0
+      @call_sites.values.each { |cs| sum += cs.invocation_count }
+      return sum
+    end
+
+    # Gets the unique count of CallSites representing the unique number of
+    # locations where this DeprecatedMethod was invoked.
+    #
+    # Returnts the Integer unique count of CallSites.
+    def call_site_count
+      @call_sites.size
+    end
+
+    ###################################################################
+    private
+    ###################################################################
+
+    # Find the CallSite representing the given file and line_number. It creates
+    # a new CallSite instance if necessary.
+    #
+    # file        - The String path to the file in which the DeprecatedMethod
+    #               was invoked.
+    # line_number - The Integer line_number in the file on which the
+    #               DeprecatedMethod was invoked.
+    #
+    # Returns the CallSite representing the give file and line number.
+    def call_site_for( file, line_number )
+      cs = @call_sites[CallSite.gen_key( file, line_number)]
+      if cs.nil? then
+        cs = CallSite.new( file, line_number, ::Deprecatable.options.caller_context_padding  )
+        @call_sites[cs.key] = cs
+      end
+      return cs
+    end
+
+    # Create the wrapper method that replaces the deprecated method. This is
+    # where the magic happens.
+    #
+    # This does the following:
+    #
+    # 1) aliases the deprecated method to a new method name
+    # 2) creates a new method with the original name that
+    #    1) logs the invocation of the deprecated method 
+    #    2) calls the original deprecated method.
+    #
+    # Returns nothing.
+    def insert_shim( dm )
+      if not klass.method_defined?( dm.deprecated_method_name ) then
+
+        klass.module_eval do
+
+          alias_method dm.deprecated_method_name, dm.method
+
+          define_method( dm.method ) do |*args, &block|
+            dm.log_invocation( *Util.location_of_caller )
+            send( dm.deprecated_method_name, *args, &block )
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/deprecatable/options.rb

@@ -0,0 +1,138 @@
+module Deprecatable
+  # A Container for the options of Deprecatable.
+  #
+  # The available options are:
+  #
+  #    caller_context_padding - The number of lines before and after the call
+  #                             site of the deprecated method to record
+  #    alert_frequency        - The maximum number of times to alert for a given
+  #                             call to the deprecated method
+  #    at_exit_report         - Whether or not a deprecation report is issued
+  #                             when the program exits
+  #
+  # These options may also be overridden with environment varaibles
+  #
+  #   DEPRECATABLE_CALLER_CONTEXT_PADDING
+  #   DEPRECATABLE_ALERT_FREQUENCY
+  #   DEPRECATABLE_AT_EXIT_REPORT
+  #
+  class Options
+    # Create a new instance of Options. All of the default values for the
+    # options are set.
+    #
+    #   caller_context_padding - 2
+    #   has_at_exit_report     - true
+    #   alert_frequency        - 1
+    def initialize
+      reset
+    end
+
+    # Reset the options to their default values.
+    #
+    # Returns nothing.
+    def reset
+      @caller_context_padding = 2
+      @has_at_exit_report     = true
+      @alert_frequency        = 1
+    end
+
+    # Public: Set the number of lines of context surrounding the call site of
+    # the deprecated method to display in the alerts and reports. (default: 2)
+    #
+    # count - The number of lines before and after the callsite to report.
+    #         This must be a positive number.
+    #
+    # Returns the count.
+    def caller_context_padding=( count )
+      raise ArgumentError, "caller_content_padding must have a count > 0" unless count > 0
+      @caller_context_padding = count
+    end
+
+    # Public: Get the number of lines of context padding.
+    #
+    # This may be overridden with the environment variable
+    # DEPRECATABLE_CALLER_CONTEXT_PADDING.
+    #
+    # Returns the Integer number of context padding lines.
+    def caller_context_padding
+      p = ENV['DEPRECATABLE_CALLER_CONTEXT_PADDING']
+      if p then
+        p = Float(p).to_i
+        raise ArgumentError, "DEPRECATABLE_CALLER_CONTEXT_APDDING must have a value > 0, it is currently #{p}" unless p > 0
+        return p
+      end
+      return @caller_context_padding
+    end
+
+    # Public: Set the maximum number of times an alert for a unqiue CallSite
+    # of a DeprecatedMethod will be emitted. (default: :once)
+    #
+    # That is, when a deprecated method is called from a particular CallSite,
+    # normally an 'alert' is sent. This setting controls the maximum number of
+    # times that the 'alert' for a particular CallSite is emitted.
+    #
+    # freq - The alert frequency. This may be set to any number, or to one of
+    #        the special token values:
+    #
+    #          :never  - Never send any alerts
+    #          :once   - Send an alert for a given CallSite only once.
+    #          :always - Send an alert for every invocation of the
+    #                    DeprecatedMethod.
+    #
+    # Returns the alert_frequency.
+    def alert_frequency=( freq )
+      @alert_frequency = frequency_of( freq )
+    end
+
+    # Public: Get the current value of the alert_frequency.
+    #
+    # This may be overridden with the environment variable
+    # DEPRECATABLE_ALERT_FREQUENCY.
+    #
+    # Returns the Integer value representing the alert_frequency.
+    def alert_frequency
+      p = ENV['DEPRECATABLE_ALERT_FREQUENCY']
+      return frequency_of(p) if p
+      return @alert_frequency
+    end
+
+    # Public: Set whether or not the final at_exit_report should be emitted
+    #
+    # bool - true or false, shall the exit report be emitted.
+    #
+    # Returns the value set.
+    attr_writer :has_at_exit_report
+
+    # Public: Say whether or not the final at exit report shall be emitted.
+    #
+    # This may be overridden by the environment variable
+    # DEPRECATABLE_HAS_AT_EXIT_REPORT. Setting the environment variable to
+    # 'true' will override the existing setting.
+    #
+    # Returns the boolean of whether or not the exti report should be done.
+    def has_at_exit_report?
+      return true if ENV['DEPRECATABLE_HAS_AT_EXIT_REPORT'] == "true"
+      return @has_at_exit_report
+    end
+
+    ##################################################################
+    private
+    ##################################################################
+
+    # Convert the given frequency Symbol/String into its Numeric representation.
+    #
+    # Return the Numeric value of the input frequency.
+    def frequency_of( frequency )
+      case frequency.to_s
+      when 'always'
+        (1.0/0.0)
+      when 'once'
+        1
+      when 'never'
+        0
+      else
+        Float(frequency).to_i
+      end
+    end
+  end
+end

data/lib/deprecatable/registry.rb

@@ -0,0 +1,55 @@
+module Deprecatable
+  # The Registry is a container of unique DeprecatedMethod instances.
+  # Normally there is only one in existence and it is accessed via
+  # 'Deprecatable.registry'
+  class Registry
+    # Initialize the Registry, which amounts to creating a new Hash.
+    #
+    # Returns nothing.
+    def initialize
+      @registry = Hash.new
+    end
+
+    # Public: Return the number of instances of DeprecatedMethod there are in
+    # the Registry.
+    #
+    # Returns an Integer of the size of the Regsitry.
+    def size()
+      @registry.size
+    end
+
+    # Public: Iterate over all items in the Registry
+    #
+    # Yields each DeprecatedMethod in the Registry
+    # Returns nothing.
+    def each
+      items.each do |i|
+        yield i
+      end
+    end
+
+    # Public: Remove all items from the Registry.
+    #
+    # Returns nothing.
+    def clear
+      @registry.clear
+    end
+
+    # Public: Register a method to be deprecated.
+    #
+    # method - An instance of DeprecatedMethod
+    #
+    # Returns the instance that was passed in.
+    def register( dm )
+      @registry[dm] = true
+      return dm
+    end
+
+    # Public: Return all the DeprecatedMethod instances in the registry.
+    #
+    # Returns an Array of DeprecatedMethod instances.
+    def items
+      @registry.keys
+    end
+  end
+end

data/lib/deprecatable/util.rb

@@ -0,0 +1,26 @@
+module Deprecatable
+  # Common utility functions used by all the Deprecatable modules and classes
+  module Util
+    # Find the caller of the method that called the method where
+    # location_of_call was invoked.
+    #
+    # Example:
+    #
+    #     def foo
+    #       bar()  # <--- this file and line number is returned
+    #     end
+    #
+    #     def bar
+    #       Deprecatable::Util.location_of_caller
+    #     end
+    #
+    # Return the [ file, line number] tuple from which bar() was invoked.
+    def self.location_of_caller
+      call_line     = caller[1]
+      file, line, _ = call_line.split(':')
+      file          = File.expand_path( file )
+      line          = Float(line).to_i
+      return file, line
+    end
+  end
+end

data/test/helpers.rb

@@ -0,0 +1,18 @@
+gem "minitest" # required for ruby 1.9 and 'rake rcov'
+require 'minitest/autorun'
+require 'deprecatable'
+
+::Deprecatable.options.has_at_exit_report = false
+
+module MiniTest
+  class Unit
+    class TestCase
+      def assert_array_equal( expected, actual, msg = nil )
+        assert_equal( expected.size, actual.size, msg )
+        expected.each_with_index do |i, idx|
+          assert_equal( i, actual[idx], msg )
+        end
+      end
+    end
+  end
+end