deprecatable 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -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