deprecatable 1.0.0

data/.autotest

@@ -0,0 +1,9 @@
+# vim: syntax=ruby
+
+require 'autotest/restart'
+
+Autotest.add_hook :initialize do |at|
+  at.add_exception 'coverage.info'
+  at.add_exception 'coverage'
+  at.add_exception '.git'
+end

data/.gemtest

@@ -0,0 +1 @@
+

data/HISTORY.rdoc

@@ -0,0 +1,4 @@
+== 1.0.0 - 2011-08-09
+
+* Birthday!
+

data/Manifest.txt

@@ -0,0 +1,26 @@
+.autotest
+.gemtest
+HISTORY.rdoc
+Manifest.txt
+README.rdoc
+Rakefile
+examples/alert_frequency.rb
+examples/at_exit.rb
+examples/caller_context_padding.rb
+lib/deprecatable.rb
+lib/deprecatable/alerter.rb
+lib/deprecatable/call_site.rb
+lib/deprecatable/call_site_context.rb
+lib/deprecatable/deprecated_method.rb
+lib/deprecatable/options.rb
+lib/deprecatable/registry.rb
+lib/deprecatable/util.rb
+test/helpers.rb
+test/test_deprecatable.rb
+test/test_deprecatable_alerter.rb
+test/test_deprecatable_call_site.rb
+test/test_deprecatable_call_site_context.rb
+test/test_deprecatable_deprecated_method.rb
+test/test_deprecatable_options.rb
+test/test_deprecatable_registry.rb
+test/test_deprecatable_util.rb

data/README.rdoc

@@ -0,0 +1,175 @@
+= Deprecatable
+
+* http://github.com/copiousfreetime/deprecatable
+* http://www.copiousfreetime.org/projects/deprecatable
+
+== DESCRIPTION
+
+Deprecatable is a library to help you, as a developer, deprecate your API and be
+proactive about helping people who use your library find where they need to
+update.
+
+When using Deprecatable, you mark methods as 'deperecated' and then the users of
+your API will receive a helpful alert showing the exact line of code where they
+called the deprecated API, and what they need to do to fix it (although you need
+to supply this piece of information).
+
+Users will receive, by default, a single alert for each unique location a
+deprecated API method is invoked. They will also receive a final report
+detailing all the locations where deprecated APIs were invoked.
+
+The "noisiness" of the alerting and the final report is all configurable, via
+both code, and environment variables. See Deprecatable::Options.
+
+== SYNOPSIS
+
+  class SomeClass
+    extend Deprecatable
+
+    def deprecate_me
+    ...
+    end
+    deprecated :deprecate_me
+  end
+
+== REQUIREMENTS
+
+No runtime requirements, other than Ruby itself.
+
+== INSTALL
+
+  $ [sudo] gem install deprecatable
+
+== EXAMPLES
+
+All of the examles here are included in the examples/ directory.
+
+=== Alerts
+
+Default alerting. Uses Ruby's 'warn' capability, which sends the output to
+standard error.
+
+  $ ruby -Ilib examples/alert_frequency.rb once > /dev/null
+  DEPRECATION WARNING: `A::B#deprecate_me`
+  DEPRECATION WARNING: -------------------
+  DEPRECATION WARNING:
+  DEPRECATION WARNING: * Originally defined at /Users/jeremy/Projects/deprecatable/examples/alert_frequency.rb:24
+  DEPRECATION WARNING: * This method is to be completely removed
+  DEPRECATION WARNING: * Will be removed in version 4.2
+  DEPRECATION WARNING:
+  DEPRECATION WARNING: Called from /Users/jeremy/Projects/deprecatable/examples/alert_frequency.rb:89
+  DEPRECATION WARNING:
+  DEPRECATION WARNING:          87:     # Context before 1.1
+  DEPRECATION WARNING:          88:     # Context before 1.2
+  DEPRECATION WARNING:     ---> 89:     b.deprecate_me
+  DEPRECATION WARNING:          90:     # Context after 1.1
+  DEPRECATION WARNING:          91:     # Context after 1.2
+  DEPRECATION WARNING:
+  DEPRECATION WARNING: To turn this report off do one of the following:
+  DEPRECATION WARNING: * in your ruby code set `Deprecatable.options.alert_frequency = :never`
+  DEPRECATION WARNING: * set the environment variable `DEPRECATABLE_ALERT_FREQUENCY="never"`
+  DEPRECATION WARNING:
+
+Lets try that again and shut off the output
+
+  $ DEPRECATABLE_ALERT_FREQUENCY=never ruby -Ilib examples/alert_frequency.rb once > /dev/null
+  $
+
+=== A final report when the process exits.
+
+As a bonus, the 'at_exit' report is valid Markdown.
+
+  $ ruby -Ilib examples/at_exit.rb > /dev/null
+  Deprecatable 'at_exit' Report
+  =============================
+
+  To turn this report off do one of the following:
+
+  * in your ruby code set `Deprecatable.options.has_at_exit_report = false`
+  * set the environment variable `DEPRECATABLE_HAS_AT_EXIT_REPORT="false"`
+
+  `A::B#deprecate_me_2`
+  ---------------------
+
+  * Originally defined at /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:24
+  * This method is to be completely removed
+  * Will be removed after 2020-02-20
+
+  Called 2 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:64
+
+           62:     # Context before 4.1
+           63:     # Context before 4.2
+      ---> 64:     b.deprecate_me_2
+           65:     # Context after 4.1
+           66:     # Context after 4.2
+
+  Called 4 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:48
+
+           46:     # Context before 2.1
+           47:     # Context before 2.2
+      ---> 48:     b.deprecate_me_2
+           49:     # Context after 2.1
+           50:     # Context after 2.2
+
+  `A::B#deprecate_me_1`
+  ---------------------
+
+  * Originally defined at /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:19
+  * This method is to be completely removed
+  * Will be removed in version 4.2
+
+  Called 4 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:42
+
+           40:     # Context before 1.1
+           41:     # Context before 1.2
+      ---> 42:     b.deprecate_me_1
+           43:     # Context after 1.1
+           44:     # Context after 1.2
+
+  Called 2 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:58
+
+           56:     # Context before 3.1
+           57:     # Context before 3.2
+      ---> 58:     b.deprecate_me_1
+           59:     # Context after 3.1
+           60:     # Context after 3.2
+
+And again, shutting off the output:
+
+  $ DEPRECATABLE_HAS_AT_EXIT_REPORT="false" ruby -Ilib examples/at_exit.rb > /dev/null
+  $
+
+== DEVELOPERS
+
+If you would like to contribute to the project, you will need to check out the
+source from http://github.com/copiousfreetime/deprecatable and then if you are
+using a system installed ruby:
+
+  $ rake newb
+
+If you are using a non-root installed ruby, for instance RVM, then you
+probably want to run:
+
+  $ NOSUDO=true rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+
+== LICENSE
+
+(The ISC LICENSE) - http://www.opensource.org/licenses/ISC
+
+Copyright (c) 2011 Jeremy Hinegardner
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

data/Rakefile

@@ -0,0 +1,33 @@
+# vim: syntax=ruby
+
+begin
+  require 'rubygems'
+  require 'hoe'
+rescue LoadError 
+  abort <<-_
+  Developing deprecatable requires the use of rubygems and hoe.
+
+    gem install hoe
+  _
+end
+
+Hoe.plugin :doofus, :git, :gemspec2, :minitest
+
+Hoe.spec 'deprecatable' do
+  developer 'Jeremy Hinegardner', 'jeremy@copiousfreetime.org'
+
+  # Use rdoc for history and readme
+  self.history_file = 'HISTORY.rdoc'
+  self.readme_file  = 'README.rdoc'
+
+  self.extra_rdoc_files = [ self.readme_file, self.history_file ]
+
+  # Publish rdoc to a designated remote location
+  with_config do |config, _|
+    self.rdoc_locations << File.join(config['rdoc_remote_root'], self.remote_rdoc_dir)
+  end
+
+  self.extra_dev_deps << [ 'rcov', '~> 0.9.10']
+
+end
+

data/examples/alert_frequency.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+#
+# An example showing how the alert_frequency option works
+#
+# You probably need to run from the parent directory as:
+#
+#   ruby -Ilib examples/alert_frequency.rb
+#
+require 'deprecatable'
+
+#----------------------------------------------------------------------
+# We create an example class with a deprecated method
+#----------------------------------------------------------------------
+module A
+  class B
+    extend Deprecatable
+    def initialize
+      @call_count = 0
+    end
+    def deprecate_me
+      @call_count += 1
+      puts "deprecate_me call #{@call_count}"
+    end
+    deprecate :deprecate_me, :message => "This method is to be completely removed", :removal_version => "4.2"
+  end
+end
+
+
+#----------------------------------------------------------------------
+# usage, you can ignore this for now, this will get printed out if you
+# do not put any commandline arguments down
+#----------------------------------------------------------------------
+def usage
+  puts <<__
+This is an example of showing how to affect the alert frequency
+You can change the alert frequency by:
+
+  1) Setting `Deprecatable.options.alert_freqeuncy` in ruby code.
+  2) Setting the DEPRECATABLE_ALERT_FREQUENCY envionment variable.
+
+They may be set to one of the following values:  'never', 'once', 'always'
+When you use both (1) and (2) simultaneously, you will see that
+setting the environment variable always overrides the code.
+
+Here are some example ways to run this program
+
+__
+
+
+  [ nil, "DEPRECATABLE_ALERT_FREQUENCY=" ].each do |env|
+    %w[ never once always ].each do |env_setting|
+      next if env.nil? and env_setting != 'never'
+      %w[ never once always ].each do |cmd_line|
+        next if env and (env_setting == cmd_line)
+        parts = [ "    " ]
+        parts << "#{env}#{env_setting}" if env
+        parts << "ruby -Ilib #{__FILE__} #{cmd_line}"
+        puts parts.join(' ')
+      end
+    end
+  end
+
+  puts
+  exit 1
+end
+
+if $0 == __FILE__
+  # Turning off the at exit report, for more information on them,
+  # see the examples/at_exit.rb
+  Deprecatable.options.has_at_exit_report = false
+
+  # capture the parameters, we'll run if there is a commandline parameter
+  # of if the environment variable is et
+  alert_frequency = ARGV.shift
+  usage unless alert_frequency || ENV['DEPRECATABLE_ALERT_FREQUENCY']
+
+  Deprecatable.options.alert_frequency = alert_frequency if alert_frequency
+
+  puts
+  puts "Running with ENV['DEPRECATABLE_ALERT_FREQUENCY']  => #{ENV['DEPRECATABLE_ALERT_FREQUENCY']}"
+  puts "Running with Deprecatable.options.alert_frequency => #{Deprecatable.options.alert_frequency}"
+  puts "-" * 72
+  puts
+
+  b = A::B.new
+  4.times do
+    # Context before 1.1
+    # Context before 1.2
+    b.deprecate_me
+    # Context after 1.1
+    # Context after 1.2
+  end
+
+  2.times do
+    # Context before 2.1
+    # Context before 2.2
+    b.deprecate_me
+    # Context after 2.1
+    # Context after 2.2
+  end
+end

data/examples/at_exit.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+#
+# An example showing how the at_exit handler work
+#
+# You probably need to run from the parent directory as:
+#
+#   ruby -Ilib examples/at_exit.rb
+#
+require 'deprecatable'
+#----------------------------------------------------------------------
+# We create an example class with some deprecated methods
+#----------------------------------------------------------------------
+module A
+  class B
+    extend Deprecatable
+    def deprecate_me_1
+      puts "I've been deprecated! (1)"
+    end
+    deprecate :deprecate_me_1, :message => "This method is to be completely removed", :removal_version => "4.2"
+
+    def deprecate_me_2
+      puts "I've been deprecated! (2)"
+    end
+    deprecate :deprecate_me_2, :message => "This method is to be completely removed", :removal_date => "2020-02-20"
+  end
+end
+
+if $0 == __FILE__
+
+  # turn off the individual alerting. To see more about the behavior, look at
+  # examples/alert_frequency.rb
+  Deprecatable.options.alert_frequency = :never
+
+  # Make sure we have the at exit return turned on, it should be by default
+  Deprecatable.options.has_at_exit_report = true
+
+  b = A::B.new
+
+  4.times do
+    # Context before 1.1
+    # Context before 1.2
+    b.deprecate_me_1
+    # Context after 1.1
+    # Context after 1.2
+
+    # Context before 2.1
+    # Context before 2.2
+    b.deprecate_me_2
+    # Context after 2.1
+    # Context after 2.2
+  end
+
+  # do a bunch of things
+
+  2.times do
+    # Context before 3.1
+    # Context before 3.2
+    b.deprecate_me_1
+    # Context after 3.1
+    # Context after 3.2
+
+    # Context before 4.1
+    # Context before 4.2
+    b.deprecate_me_2
+    # Context after 4.1
+    # Context after 4.2
+  end
+end

data/examples/caller_context_padding.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+#
+# An example showing how the caller_context_padding option works
+#
+# You probably need to run from the parent directory as:
+#
+#   ruby -Ilib examples/caller_context_padding.rb
+#
+require 'deprecatable'
+
+#----------------------------------------------------------------------
+# We create an example class with a deprecated method
+#----------------------------------------------------------------------
+module A
+  class B
+    extend Deprecatable
+    def initialize
+      @call_count = 0
+    end
+    def deprecate_me
+      @call_count += 1
+      puts "deprecate_me call #{@call_count}"
+    end
+    deprecate :deprecate_me, :message => "This method is to be completely removed", :removal_version => "4.2"
+  end
+end
+
+#----------------------------------------------------------------------
+# usage, you can ignore this for now, this will get printed out if you
+# do not put any commandline arguments down
+#----------------------------------------------------------------------
+def usage
+  puts <<__
+This is an example of showing how to affect the caller context padding
+You can change the caller_context_padding by
+
+  1) Setting `Deprecatable.options.caller_context_padding` in ruby code.
+  2) Setting the DEPRECATABLE_CALLER_CONTEXT_PADDING envionment variable.
+
+They may be set to an integer value that is >= 1
+When you use both (1) and (2) simultaneously, you will see that
+setting the environment variable always overrides the code.
+
+Here are some example ways to run this program"
+
+__
+
+  [ nil, "DEPRECATABLE_CALLER_CONTEXT_PADDING=" ].each do |env|
+    (1..3).each do |env_setting|
+      next if env.nil? and env_setting > 1
+      (1..3).each do |cmd_line|
+        next if env and (env_setting == cmd_line)
+        parts = [ "    " ]
+        parts << "#{env}#{env_setting}" if env
+        parts << "ruby -Ilib #{__FILE__} #{cmd_line}"
+        puts parts.join(' ')
+      end
+    end
+  end
+  puts
+  exit 1
+end
+
+if $0 == __FILE__
+  # Turning off the at exit report, for more information on them,
+  # see the examples/at_exit.rb
+  Deprecatable.options.has_at_exit_report = false
+
+  # capture the parameters, we'll run if there is a commandline parameter
+  # of if the environment variable is et
+  caller_context_padding = ARGV.shift
+  usage unless caller_context_padding || ENV['DEPRECATABLE_CALLER_CONTEXT_PADDING']
+  Deprecatable.options.caller_context_padding = Float( caller_context_padding ).to_i if caller_context_padding
+
+  puts
+  puts "Running with ENV['DEPRECATABLE_CALLER_CONTEXT_PADDING']  => #{ENV['DEPRECATABLE_CALLER_CONTEXT_PADDING']}"
+  puts "Running with Deprecatable.options.caller_context_padding => #{Deprecatable.options.caller_context_padding}"
+  puts "-" * 72
+  puts
+
+  b = A::B.new
+  4.times do
+    # Context before 1.1
+    # Context before 1.2
+    b.deprecate_me
+    # Context after 1.1
+    # Context after 1.2
+  end
+
+  2.times do
+    # Context before 2.1
+    # Context before 2.2
+    b.deprecate_me
+    # Context after 2.1
+    # Context after 2.2
+  end
+end