deprecatable 1.0.0

data/lib/deprecatable.rb

@@ -0,0 +1,106 @@
+require 'deprecatable/options'
+require 'deprecatable/registry'
+require 'deprecatable/alerter'
+
+# Allow methods to be deprecated and record and alert when those 
+# deprecated methods are called.
+#
+# There are configurable options for the extended class:
+#
+# For example:
+#
+#   class Foo
+#     extend Deprecatable
+#
+#     def bar
+#       ...
+#     end
+#
+#     deprecate :bar, :message => "Foo#bar has been deprecated, use Foo#foo instead"
+#
+#   end
+#
+module Deprecatable
+
+  VERSION = '1.0.0'
+
+  # Public: Deprecate a method in the included class.
+  #
+  # method_name - The method in this class to deprecate.
+  # options     - a hash of the current understood options (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.
+  #
+  # returns the instance of DeprecatedMethod created to track this deprecation.
+  def deprecate( method_name, options = {} )
+    file, line = Util.location_of_caller
+    dm         = DeprecatedMethod.new( self, method_name, file, line, options )
+
+    Deprecatable.registry.register( dm )
+
+   return dm
+  end
+
+  # The global Deprecatable::Registry instance. It is set here so it is
+  # allocated at parse time.
+  @registry = Deprecatable::Registry.new
+
+  # Public: Get the global Deprecatable::Registry instance
+  #
+  # Returns the global Deprecatable::Registry instance.
+  def self.registry
+    @registry
+  end
+
+  # The global options for Deprecatable. It is set here so it is allocated at
+  # parse time.
+  @options = Deprecatable::Options.new
+
+  # Public: Access the global Options
+  #
+  # Returns the global Deprecatable::Options instance.
+  def self.options
+    @options
+  end
+
+  # The global Alerter for Deprecatable. It is set here so it is allocated at
+  # parse time.
+  @alerter = Deprecatable::Alerter.new
+
+  # Public: Access the global Alerter
+  #
+  # Returns the global Alerter instance
+  def self.alerter
+    @alerter
+  end
+
+  # Public: Set the global Alerter
+  #
+  # alerter - Generally an instance of Alerter, but may be anything that
+  #           responds_to? both :alert and :report. See the Alerter 
+  #           documetation for more information
+  #
+  # Returns nothing.
+  def self.alerter=( a )
+    @alerter = a
+  end
+end
+
+require 'deprecatable/util'
+require 'deprecatable/call_site_context'
+require 'deprecatable/call_site'
+require 'deprecatable/deprecated_method'
+
+# The at_exit handler is set at all times, and it will always fire, unless the
+# process is killed with prejudice and/or the ruby process exists using 'exit!'
+# instead of the normal 'exit'
+at_exit do
+  if ::Deprecatable.options.has_at_exit_report? then
+    ::Deprecatable.alerter.final_report
+  end
+end

data/lib/deprecatable/alerter.rb

@@ -0,0 +1,162 @@
+require 'stringio'
+module Deprecatable
+  # An Alerter formats and emits alerts, and formats and emits reports.
+  #
+  # If you wish to impelement your own Alerter class, then it must implement
+  # the following methods:
+  #
+  # * alert( DeprecatedMethod, CallSite )
+  # * final_reort()
+  #
+  # These are the two methods that are invoked by the Deprecatable system at
+  # various points.
+  #
+  class Alerter
+    # Public: Alert that the deprecated method was invoked at a specific call
+    # site.
+    #
+    # deprecated_method - an instance of DeprecatedMethod
+    # call_site         - an instance of CallSite showing this particular
+    #                     invocation
+    #
+    # Returns nothing.
+    def alert( deprecated_method, call_site )
+      lines = deprecated_method_report( deprecated_method, call_site )
+      lines << "To turn this report off do one of the following:"
+      lines << "* in your ruby code set `Deprecatable.options.alert_frequency = :never`"
+      lines << "* set the environment variable `DEPRECATABLE_ALERT_FREQUENCY=\"never\"`"
+      lines << ""
+      lines.each { |l| warn_with_prefix l }
+    end
+
+    # Public: Render the final deprecation report showing when and where all
+    # deprecated methods in the Registry were calld.
+    #
+    # registry - An instance of Deprecatable::Registry
+    #            (default: Deprecatable.registry)
+    #
+    # Returns nothing.
+    def final_report( registry = Deprecatable.registry )
+      lines = [ "Deprecatable 'at_exit' Report",
+                "=============================" ]
+      lines << ""
+      lines << "To turn this report off do one of the following:"
+      lines << ""
+      lines << "* in your ruby code set `Deprecatable.options.has_at_exit_report = false`"
+      lines << "* set the environment variable `DEPRECATABLE_HAS_AT_EXIT_REPORT=\"false\"`"
+      lines << ""
+
+      registry.items.each do |dm|
+        lines += deprecated_method_report( dm )
+      end
+      lines.each { |l| warn_without_prefix l }
+    end
+
+    ###################################################################
+    private
+    ###################################################################
+
+    # Format a report of the data in a DeprecatedMethod
+    #
+    # dm        - A DeprecatedMethod instance
+    # call_site - A CallSite instance (default :nil)
+    #
+    # Returns an Array of Strings which are the lines of the report.
+    def deprecated_method_report( dm, call_site = nil )
+      m = "`#{dm.klass}##{dm.method}`"
+      lines = [ m ]
+      lines << "-" * m.length
+      lines << ""
+      lines << "* Originally defined at #{dm.file}:#{dm.line_number}"
+
+      if msg = dm.message then
+        lines << "* #{msg}"
+      end
+      if rd = dm.removal_date then
+        lines << "* Will be removed after #{rd}"
+      end
+
+      if rv = dm.removal_version then
+        lines << "* Will be removed in version #{rv}"
+      end
+      lines << ""
+
+      if call_site then
+        lines += call_site_report( call_site )
+      else
+        dm.call_sites.each do |cs|
+          lines += call_site_report( cs, true )
+        end
+      end
+      return lines
+    end
+
+    # Format a report about a CallSite
+    #
+    # cs            - A CallSite instance
+    # include_count - Should the report include the invocation count from the
+    #                 CallSite instance. (default: false)
+    #
+    # Returns an Array of Strings which are the lines of the report.
+    def call_site_report( cs, include_count = false )
+      header = [ "Called" ]
+      header << "#{cs.invocation_count} time(s)" if include_count
+      header << "from #{cs.file}:#{cs.line_number}"
+
+      lines = [ header.join(' ') ]
+      lines << ""
+      cs.formatted_context_lines.each do |l|
+        lines << "    #{l.rstrip}"
+      end
+      lines << ""
+      return lines
+    end
+
+    # Emit a warning message without a prefix to the message.
+    #
+    # Returns nothing.
+    def warn_without_prefix( msg = "" )
+      warn msg
+    end
+
+    # Emit a warning message WITH a prefix to the message.
+    #
+    # Returns nothing.
+    def warn_with_prefix( msg = "" )
+      warn "DEPRECATION WARNING: #{msg}"
+    end
+
+    # Emit a warning message.
+    #
+    # Returns nothing.
+    def warn( msg )
+      Kernel.warn( msg )
+    end
+  end
+
+  # StringIOAlerter is used to capture all alerts in an instance of StringIO
+  # instead of emitting them as Ruby warnings. This is mainly used in testing,
+  # and may have uses in other situations too.
+  class StringIOAlerter < Alerter
+    # Initialize the StringIOAlerter
+    #
+    # Returns nothing.
+    def initialize
+      @stringio = StringIO.new
+    end
+
+    # Capture the warning into the StringIO instance
+    #
+    # Returns nothing.
+    def warn( msg )
+      @stringio.puts msg
+    end
+
+    # Access the contens of the internal StringIO instance.
+    #
+    # Returns a String containing all the warnings so far.
+    def to_s
+      @stringio.string
+    end
+  end
+end

data/lib/deprecatable/call_site.rb

@@ -0,0 +1,91 @@
+require 'deprecatable/call_site_context'
+module Deprecatable
+  # CallSite represents a location in the source code where a DeprecatedMethod
+  # was invoked. It contains the location of the call site, the number of times
+  # that it was invoked, and an extraction of the source code around the
+  # invocation site
+  class CallSite
+    # Generate the hash key for a call site with the given file and line
+    # number.
+    #
+    # file        - A String that is the filesystem path to a file.
+    # line_number - An Integer that is the line number in the given file.
+    #
+    # Returns a String that is generally used as a unique key.
+    def self.gen_key( file, line_number )
+      "#{file}:#{line_number}"
+    end
+
+    # Public: Get the fully expand path of the file of the CallSite
+    #
+    # Returns the String filesystem path of the file.
+    attr_reader :file
+
+    # Public: Get the line number of the CallSite in the file.
+    # Line numbers start at 1.
+    #
+    # Returns the line number of a line in the file.
+    attr_reader :line_number
+
+    # Public: Gets the number of lines before and after the line_nubmer
+    # to also capture when gettin the context.
+    #
+    # This number is the number both before AND after 'line_number' to
+    # capture. If this number is 2, then the total number of lines captured
+    # should be 5. 2 before, the line in question, and 2 after.
+    #
+    # Returns the number of lines
+    attr_reader :context_padding
+
+    # Public: The number of times this CallSite has been invoked.
+    #
+    # Returns the Integer number of times this call site has been invoked.
+    attr_reader :invocation_count
+
+    # Create a new instance of CallSite
+    #
+    # file            - A String pathname of the file where the CallSite
+    #                   happend
+    # line_number     - The Integer line number in the file.
+    # context_padding - The Integer number of lines both before and after
+    #                   the 'line_nubmer' to capture.
+    def initialize( file, line_number, context_padding )
+      @file             = File.expand_path( file )
+      @line_number      = line_number
+      @context_padding  = context_padding
+      @invocation_count = 0
+    end
+
+    # The unique identifier of this CallSite.
+    #
+    # Returns the String key of this CallSite.
+    def key
+      CallSite.gen_key( file, line_number )
+    end
+
+    # Increment the invocation count by the amount given
+    #
+    # count - The amount to increment the invocation count by
+    #         This should rarely, if ever be set.
+    #         (default: 1)
+    #
+    # Returns the Integer invocation count.
+    def increment_invocation_count( count = 1 )
+      @invocation_count += count
+    end
+
+    # Retrieve the lazily loaded CallSiteContext.
+    #
+    # Returns an instances of CallSiteContext
+    def context
+      @context ||= CallSiteContext.new( @file, @line_number, @context_padding )
+    end
+
+    # Access the lines of the context in a nicely formatted way.
+    #
+    # Returns an Array of Strings containing the formatted context.
+    def formatted_context_lines
+      context.formatted_context_lines
+    end
+  end
+end

data/lib/deprecatable/call_site_context.rb

@@ -0,0 +1,112 @@
+module Deprecatable
+  # CallSiteContext captures the actual file context of the call site.
+  # It goes to the source file and extracts the lines around the line in
+  # question with the given padding and keeps it available for emitting
+  class CallSiteContext
+    # Public: The raw lines from the source file containing the context.
+    #
+    # Returns an Array of Strings of the lines from the file.
+    attr_reader :context_lines
+
+    # Public: The raw line numbers from the source file. The lines of
+    # a source file start with 1. This is a parallel array to 'context_lines'
+    #
+    # Returns an Array of Integers of the line numbers from the flie.
+    attr_reader :context_line_numbers
+
+    # The marker used to prefix the formatted context line of the exact line of
+    # the context where the CallSite took place
+    #
+    # Returns a String.
+    def self.pointer
+      "--->"
+    end
+
+    # The prefix to put in front of the CallSite context padding lines.
+    #
+    # Returns a String of blanks the same length as 'pointer'
+    def self.not_pointer
+      " " * pointer.length
+    end
+
+    # Create a new CallSiteContext. Upon instantiation, this will go to the
+    # source file in question, and extract the CallSite line and a certain
+    # number of 'padding' lines around it.
+    #
+    # file        - The String pathname of the file from which to extract lines.
+    # line_number - The 1 indexed line number within the file to be the center
+    #               of the extracted context.
+    # padding     - The Number of lines before and after 'line_number' to
+    #               extract along with the text at 'line_number'
+    #
+    # Returns nothing.
+    def initialize( file, line_number, padding )
+      @file                 = file
+      @line_number          = line_number
+      @padding              = padding
+
+      @context_line_numbers    = []
+      @context_lines           = []
+      @context_index           = @padding + 1
+      @formatted_context_lines = []
+
+      extract_context()
+    end
+
+    # Nicely format the context lines extracted from the file.
+    #
+    # Returns an Array of Strings containing the formatted lines.
+    def formatted_context_lines
+      if @formatted_context_lines.empty? then
+        number_width = ("%d" % @context_line_numbers.last).length
+        @context_lines.each_with_index do |line, idx|
+          prefix = (idx == @context_index) ? CallSiteContext.pointer : CallSiteContext.not_pointer
+          number = ("%d" % @context_line_numbers[idx]).rjust( number_width )
+          @formatted_context_lines << "#{prefix} #{number}: #{line}"
+        end
+      end
+      return @formatted_context_lines
+    end
+
+    ###########################################################################
+    private
+    ###########################################################################
+
+    # Extract the context from the source file. This goes to the file in
+    # question, and extracts the line_number and the padding lines both
+    # before and after the line_number. If the padding would cause the context
+    # to go before the first line of the file, or after the last line of the
+    # file, the padding is truncated accordingly.
+    #
+    # The result of this operation is the setting of many instance
+    # variables
+    #
+    #   @context_lines        - An Array of String containging the line_number
+    #                           line from the file and the 'padding' lines
+    #                           before and after it.
+    #   @context_index        - The index into @context_lines of the
+    #                           line_number line from the file
+    #   @context_line_numbers - An Array of Integers that paralles
+    #                           @context_lines contianing the 1 indexed line
+    #                           numbers from the file corresponding to the lines
+    #                           in @context_lines.
+    #
+    # Returns nothing.
+    def extract_context
+      if File.readable?( @file ) then
+        file_lines            = IO.readlines( @file )
+        @line_index           = @line_number - 1
+
+        start_line            = @line_index - @padding
+        start_line            = 0 if start_line < 0
+
+        stop_line             = @line_index + @padding
+        stop_line             = (file_lines.size - 1) if stop_line >= file_lines.size
+
+        @context_index        = @line_index - start_line
+        @context_line_numbers = (start_line+1..stop_line+1).to_a
+        @context_lines        = file_lines[start_line, @context_line_numbers.size]
+      end
+    end
+  end
+end