deprecatable 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,9 @@
1
+ # vim: syntax=ruby
2
+
3
+ require 'autotest/restart'
4
+
5
+ Autotest.add_hook :initialize do |at|
6
+ at.add_exception 'coverage.info'
7
+ at.add_exception 'coverage'
8
+ at.add_exception '.git'
9
+ end
@@ -0,0 +1 @@
1
+
@@ -0,0 +1,4 @@
1
+ == 1.0.0 - 2011-08-09
2
+
3
+ * Birthday!
4
+
@@ -0,0 +1,26 @@
1
+ .autotest
2
+ .gemtest
3
+ HISTORY.rdoc
4
+ Manifest.txt
5
+ README.rdoc
6
+ Rakefile
7
+ examples/alert_frequency.rb
8
+ examples/at_exit.rb
9
+ examples/caller_context_padding.rb
10
+ lib/deprecatable.rb
11
+ lib/deprecatable/alerter.rb
12
+ lib/deprecatable/call_site.rb
13
+ lib/deprecatable/call_site_context.rb
14
+ lib/deprecatable/deprecated_method.rb
15
+ lib/deprecatable/options.rb
16
+ lib/deprecatable/registry.rb
17
+ lib/deprecatable/util.rb
18
+ test/helpers.rb
19
+ test/test_deprecatable.rb
20
+ test/test_deprecatable_alerter.rb
21
+ test/test_deprecatable_call_site.rb
22
+ test/test_deprecatable_call_site_context.rb
23
+ test/test_deprecatable_deprecated_method.rb
24
+ test/test_deprecatable_options.rb
25
+ test/test_deprecatable_registry.rb
26
+ test/test_deprecatable_util.rb
@@ -0,0 +1,175 @@
1
+ = Deprecatable
2
+
3
+ * http://github.com/copiousfreetime/deprecatable
4
+ * http://www.copiousfreetime.org/projects/deprecatable
5
+
6
+ == DESCRIPTION
7
+
8
+ Deprecatable is a library to help you, as a developer, deprecate your API and be
9
+ proactive about helping people who use your library find where they need to
10
+ update.
11
+
12
+ When using Deprecatable, you mark methods as 'deperecated' and then the users of
13
+ your API will receive a helpful alert showing the exact line of code where they
14
+ called the deprecated API, and what they need to do to fix it (although you need
15
+ to supply this piece of information).
16
+
17
+ Users will receive, by default, a single alert for each unique location a
18
+ deprecated API method is invoked. They will also receive a final report
19
+ detailing all the locations where deprecated APIs were invoked.
20
+
21
+ The "noisiness" of the alerting and the final report is all configurable, via
22
+ both code, and environment variables. See Deprecatable::Options.
23
+
24
+ == SYNOPSIS
25
+
26
+ class SomeClass
27
+ extend Deprecatable
28
+
29
+ def deprecate_me
30
+ ...
31
+ end
32
+ deprecated :deprecate_me
33
+ end
34
+
35
+ == REQUIREMENTS
36
+
37
+ No runtime requirements, other than Ruby itself.
38
+
39
+ == INSTALL
40
+
41
+ $ [sudo] gem install deprecatable
42
+
43
+ == EXAMPLES
44
+
45
+ All of the examles here are included in the examples/ directory.
46
+
47
+ === Alerts
48
+
49
+ Default alerting. Uses Ruby's 'warn' capability, which sends the output to
50
+ standard error.
51
+
52
+ $ ruby -Ilib examples/alert_frequency.rb once > /dev/null
53
+ DEPRECATION WARNING: `A::B#deprecate_me`
54
+ DEPRECATION WARNING: -------------------
55
+ DEPRECATION WARNING:
56
+ DEPRECATION WARNING: * Originally defined at /Users/jeremy/Projects/deprecatable/examples/alert_frequency.rb:24
57
+ DEPRECATION WARNING: * This method is to be completely removed
58
+ DEPRECATION WARNING: * Will be removed in version 4.2
59
+ DEPRECATION WARNING:
60
+ DEPRECATION WARNING: Called from /Users/jeremy/Projects/deprecatable/examples/alert_frequency.rb:89
61
+ DEPRECATION WARNING:
62
+ DEPRECATION WARNING: 87: # Context before 1.1
63
+ DEPRECATION WARNING: 88: # Context before 1.2
64
+ DEPRECATION WARNING: ---> 89: b.deprecate_me
65
+ DEPRECATION WARNING: 90: # Context after 1.1
66
+ DEPRECATION WARNING: 91: # Context after 1.2
67
+ DEPRECATION WARNING:
68
+ DEPRECATION WARNING: To turn this report off do one of the following:
69
+ DEPRECATION WARNING: * in your ruby code set `Deprecatable.options.alert_frequency = :never`
70
+ DEPRECATION WARNING: * set the environment variable `DEPRECATABLE_ALERT_FREQUENCY="never"`
71
+ DEPRECATION WARNING:
72
+
73
+ Lets try that again and shut off the output
74
+
75
+ $ DEPRECATABLE_ALERT_FREQUENCY=never ruby -Ilib examples/alert_frequency.rb once > /dev/null
76
+ $
77
+
78
+ === A final report when the process exits.
79
+
80
+ As a bonus, the 'at_exit' report is valid Markdown.
81
+
82
+ $ ruby -Ilib examples/at_exit.rb > /dev/null
83
+ Deprecatable 'at_exit' Report
84
+ =============================
85
+
86
+ To turn this report off do one of the following:
87
+
88
+ * in your ruby code set `Deprecatable.options.has_at_exit_report = false`
89
+ * set the environment variable `DEPRECATABLE_HAS_AT_EXIT_REPORT="false"`
90
+
91
+ `A::B#deprecate_me_2`
92
+ ---------------------
93
+
94
+ * Originally defined at /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:24
95
+ * This method is to be completely removed
96
+ * Will be removed after 2020-02-20
97
+
98
+ Called 2 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:64
99
+
100
+ 62: # Context before 4.1
101
+ 63: # Context before 4.2
102
+ ---> 64: b.deprecate_me_2
103
+ 65: # Context after 4.1
104
+ 66: # Context after 4.2
105
+
106
+ Called 4 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:48
107
+
108
+ 46: # Context before 2.1
109
+ 47: # Context before 2.2
110
+ ---> 48: b.deprecate_me_2
111
+ 49: # Context after 2.1
112
+ 50: # Context after 2.2
113
+
114
+ `A::B#deprecate_me_1`
115
+ ---------------------
116
+
117
+ * Originally defined at /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:19
118
+ * This method is to be completely removed
119
+ * Will be removed in version 4.2
120
+
121
+ Called 4 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:42
122
+
123
+ 40: # Context before 1.1
124
+ 41: # Context before 1.2
125
+ ---> 42: b.deprecate_me_1
126
+ 43: # Context after 1.1
127
+ 44: # Context after 1.2
128
+
129
+ Called 2 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:58
130
+
131
+ 56: # Context before 3.1
132
+ 57: # Context before 3.2
133
+ ---> 58: b.deprecate_me_1
134
+ 59: # Context after 3.1
135
+ 60: # Context after 3.2
136
+
137
+ And again, shutting off the output:
138
+
139
+ $ DEPRECATABLE_HAS_AT_EXIT_REPORT="false" ruby -Ilib examples/at_exit.rb > /dev/null
140
+ $
141
+
142
+ == DEVELOPERS
143
+
144
+ If you would like to contribute to the project, you will need to check out the
145
+ source from http://github.com/copiousfreetime/deprecatable and then if you are
146
+ using a system installed ruby:
147
+
148
+ $ rake newb
149
+
150
+ If you are using a non-root installed ruby, for instance RVM, then you
151
+ probably want to run:
152
+
153
+ $ NOSUDO=true rake newb
154
+
155
+ This task will install any missing dependencies, run the tests/specs,
156
+ and generate the RDoc.
157
+
158
+
159
+ == LICENSE
160
+
161
+ (The ISC LICENSE) - http://www.opensource.org/licenses/ISC
162
+
163
+ Copyright (c) 2011 Jeremy Hinegardner
164
+
165
+ Permission to use, copy, modify, and/or distribute this software for any purpose
166
+ with or without fee is hereby granted, provided that the above copyright notice
167
+ and this permission notice appear in all copies.
168
+
169
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
170
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
171
+ FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
172
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
173
+ OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
174
+ TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
175
+ THIS SOFTWARE.
@@ -0,0 +1,33 @@
1
+ # vim: syntax=ruby
2
+
3
+ begin
4
+ require 'rubygems'
5
+ require 'hoe'
6
+ rescue LoadError
7
+ abort <<-_
8
+ Developing deprecatable requires the use of rubygems and hoe.
9
+
10
+ gem install hoe
11
+ _
12
+ end
13
+
14
+ Hoe.plugin :doofus, :git, :gemspec2, :minitest
15
+
16
+ Hoe.spec 'deprecatable' do
17
+ developer 'Jeremy Hinegardner', 'jeremy@copiousfreetime.org'
18
+
19
+ # Use rdoc for history and readme
20
+ self.history_file = 'HISTORY.rdoc'
21
+ self.readme_file = 'README.rdoc'
22
+
23
+ self.extra_rdoc_files = [ self.readme_file, self.history_file ]
24
+
25
+ # Publish rdoc to a designated remote location
26
+ with_config do |config, _|
27
+ self.rdoc_locations << File.join(config['rdoc_remote_root'], self.remote_rdoc_dir)
28
+ end
29
+
30
+ self.extra_dev_deps << [ 'rcov', '~> 0.9.10']
31
+
32
+ end
33
+
@@ -0,0 +1,101 @@
1
+ #!/usr/bin/env ruby
2
+ #
3
+ # An example showing how the alert_frequency option works
4
+ #
5
+ # You probably need to run from the parent directory as:
6
+ #
7
+ # ruby -Ilib examples/alert_frequency.rb
8
+ #
9
+ require 'deprecatable'
10
+
11
+ #----------------------------------------------------------------------
12
+ # We create an example class with a deprecated method
13
+ #----------------------------------------------------------------------
14
+ module A
15
+ class B
16
+ extend Deprecatable
17
+ def initialize
18
+ @call_count = 0
19
+ end
20
+ def deprecate_me
21
+ @call_count += 1
22
+ puts "deprecate_me call #{@call_count}"
23
+ end
24
+ deprecate :deprecate_me, :message => "This method is to be completely removed", :removal_version => "4.2"
25
+ end
26
+ end
27
+
28
+
29
+ #----------------------------------------------------------------------
30
+ # usage, you can ignore this for now, this will get printed out if you
31
+ # do not put any commandline arguments down
32
+ #----------------------------------------------------------------------
33
+ def usage
34
+ puts <<__
35
+ This is an example of showing how to affect the alert frequency
36
+ You can change the alert frequency by:
37
+
38
+ 1) Setting `Deprecatable.options.alert_freqeuncy` in ruby code.
39
+ 2) Setting the DEPRECATABLE_ALERT_FREQUENCY envionment variable.
40
+
41
+ They may be set to one of the following values: 'never', 'once', 'always'
42
+ When you use both (1) and (2) simultaneously, you will see that
43
+ setting the environment variable always overrides the code.
44
+
45
+ Here are some example ways to run this program
46
+
47
+ __
48
+
49
+
50
+ [ nil, "DEPRECATABLE_ALERT_FREQUENCY=" ].each do |env|
51
+ %w[ never once always ].each do |env_setting|
52
+ next if env.nil? and env_setting != 'never'
53
+ %w[ never once always ].each do |cmd_line|
54
+ next if env and (env_setting == cmd_line)
55
+ parts = [ " " ]
56
+ parts << "#{env}#{env_setting}" if env
57
+ parts << "ruby -Ilib #{__FILE__} #{cmd_line}"
58
+ puts parts.join(' ')
59
+ end
60
+ end
61
+ end
62
+
63
+ puts
64
+ exit 1
65
+ end
66
+
67
+ if $0 == __FILE__
68
+ # Turning off the at exit report, for more information on them,
69
+ # see the examples/at_exit.rb
70
+ Deprecatable.options.has_at_exit_report = false
71
+
72
+ # capture the parameters, we'll run if there is a commandline parameter
73
+ # of if the environment variable is et
74
+ alert_frequency = ARGV.shift
75
+ usage unless alert_frequency || ENV['DEPRECATABLE_ALERT_FREQUENCY']
76
+
77
+ Deprecatable.options.alert_frequency = alert_frequency if alert_frequency
78
+
79
+ puts
80
+ puts "Running with ENV['DEPRECATABLE_ALERT_FREQUENCY'] => #{ENV['DEPRECATABLE_ALERT_FREQUENCY']}"
81
+ puts "Running with Deprecatable.options.alert_frequency => #{Deprecatable.options.alert_frequency}"
82
+ puts "-" * 72
83
+ puts
84
+
85
+ b = A::B.new
86
+ 4.times do
87
+ # Context before 1.1
88
+ # Context before 1.2
89
+ b.deprecate_me
90
+ # Context after 1.1
91
+ # Context after 1.2
92
+ end
93
+
94
+ 2.times do
95
+ # Context before 2.1
96
+ # Context before 2.2
97
+ b.deprecate_me
98
+ # Context after 2.1
99
+ # Context after 2.2
100
+ end
101
+ end
@@ -0,0 +1,68 @@
1
+ #!/usr/bin/env ruby
2
+ #
3
+ # An example showing how the at_exit handler work
4
+ #
5
+ # You probably need to run from the parent directory as:
6
+ #
7
+ # ruby -Ilib examples/at_exit.rb
8
+ #
9
+ require 'deprecatable'
10
+ #----------------------------------------------------------------------
11
+ # We create an example class with some deprecated methods
12
+ #----------------------------------------------------------------------
13
+ module A
14
+ class B
15
+ extend Deprecatable
16
+ def deprecate_me_1
17
+ puts "I've been deprecated! (1)"
18
+ end
19
+ deprecate :deprecate_me_1, :message => "This method is to be completely removed", :removal_version => "4.2"
20
+
21
+ def deprecate_me_2
22
+ puts "I've been deprecated! (2)"
23
+ end
24
+ deprecate :deprecate_me_2, :message => "This method is to be completely removed", :removal_date => "2020-02-20"
25
+ end
26
+ end
27
+
28
+ if $0 == __FILE__
29
+
30
+ # turn off the individual alerting. To see more about the behavior, look at
31
+ # examples/alert_frequency.rb
32
+ Deprecatable.options.alert_frequency = :never
33
+
34
+ # Make sure we have the at exit return turned on, it should be by default
35
+ Deprecatable.options.has_at_exit_report = true
36
+
37
+ b = A::B.new
38
+
39
+ 4.times do
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
45
+
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
51
+ end
52
+
53
+ # do a bunch of things
54
+
55
+ 2.times do
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
61
+
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
67
+ end
68
+ end
@@ -0,0 +1,97 @@
1
+ #!/usr/bin/env ruby
2
+ #
3
+ # An example showing how the caller_context_padding option works
4
+ #
5
+ # You probably need to run from the parent directory as:
6
+ #
7
+ # ruby -Ilib examples/caller_context_padding.rb
8
+ #
9
+ require 'deprecatable'
10
+
11
+ #----------------------------------------------------------------------
12
+ # We create an example class with a deprecated method
13
+ #----------------------------------------------------------------------
14
+ module A
15
+ class B
16
+ extend Deprecatable
17
+ def initialize
18
+ @call_count = 0
19
+ end
20
+ def deprecate_me
21
+ @call_count += 1
22
+ puts "deprecate_me call #{@call_count}"
23
+ end
24
+ deprecate :deprecate_me, :message => "This method is to be completely removed", :removal_version => "4.2"
25
+ end
26
+ end
27
+
28
+ #----------------------------------------------------------------------
29
+ # usage, you can ignore this for now, this will get printed out if you
30
+ # do not put any commandline arguments down
31
+ #----------------------------------------------------------------------
32
+ def usage
33
+ puts <<__
34
+ This is an example of showing how to affect the caller context padding
35
+ You can change the caller_context_padding by
36
+
37
+ 1) Setting `Deprecatable.options.caller_context_padding` in ruby code.
38
+ 2) Setting the DEPRECATABLE_CALLER_CONTEXT_PADDING envionment variable.
39
+
40
+ They may be set to an integer value that is >= 1
41
+ When you use both (1) and (2) simultaneously, you will see that
42
+ setting the environment variable always overrides the code.
43
+
44
+ Here are some example ways to run this program"
45
+
46
+ __
47
+
48
+ [ nil, "DEPRECATABLE_CALLER_CONTEXT_PADDING=" ].each do |env|
49
+ (1..3).each do |env_setting|
50
+ next if env.nil? and env_setting > 1
51
+ (1..3).each do |cmd_line|
52
+ next if env and (env_setting == cmd_line)
53
+ parts = [ " " ]
54
+ parts << "#{env}#{env_setting}" if env
55
+ parts << "ruby -Ilib #{__FILE__} #{cmd_line}"
56
+ puts parts.join(' ')
57
+ end
58
+ end
59
+ end
60
+ puts
61
+ exit 1
62
+ end
63
+
64
+ if $0 == __FILE__
65
+ # Turning off the at exit report, for more information on them,
66
+ # see the examples/at_exit.rb
67
+ Deprecatable.options.has_at_exit_report = false
68
+
69
+ # capture the parameters, we'll run if there is a commandline parameter
70
+ # of if the environment variable is et
71
+ caller_context_padding = ARGV.shift
72
+ usage unless caller_context_padding || ENV['DEPRECATABLE_CALLER_CONTEXT_PADDING']
73
+ Deprecatable.options.caller_context_padding = Float( caller_context_padding ).to_i if caller_context_padding
74
+
75
+ puts
76
+ puts "Running with ENV['DEPRECATABLE_CALLER_CONTEXT_PADDING'] => #{ENV['DEPRECATABLE_CALLER_CONTEXT_PADDING']}"
77
+ puts "Running with Deprecatable.options.caller_context_padding => #{Deprecatable.options.caller_context_padding}"
78
+ puts "-" * 72
79
+ puts
80
+
81
+ b = A::B.new
82
+ 4.times do
83
+ # Context before 1.1
84
+ # Context before 1.2
85
+ b.deprecate_me
86
+ # Context after 1.1
87
+ # Context after 1.2
88
+ end
89
+
90
+ 2.times do
91
+ # Context before 2.1
92
+ # Context before 2.2
93
+ b.deprecate_me
94
+ # Context after 2.1
95
+ # Context after 2.2
96
+ end
97
+ end