1 package Package::DeprecationManager;
7 use Params::Util qw( _HASH );
15 'You must provide a hash reference -deprecations parameter when importing Package::DeprecationManager'
16 unless $args{-deprecations} && _HASH( $args{-deprecations} );
20 my $import = _build_import( \%registry );
21 my $warn = _build_warn( \%registry, $args{-deprecations}, $args{-ignore} );
23 my $caller = caller();
25 Sub::Install::install_sub(
33 Sub::Install::install_sub(
51 $args{-api_version} ||= delete $args{-compatible};
53 $registry->{ caller() } = $args{-api_version}
54 if $args{-api_version};
62 my $deprecated_at = shift;
65 my %ignore = map { $_ => 1 } @{ $ignore || [] };
70 my %args = @_ < 2 ? ( message => shift ) : @_;
72 my ( $package, undef, undef, $sub ) = caller(1);
76 while ( defined $package && $ignore{$package} ) {
77 # We want to start two levels back, since we already looked
78 # one level back and found an internal package.
79 $package = caller($skipped++ + 2);
84 $package = 'unknown package' unless defined $package;
86 unless ( defined $args{feature} ) {
87 $args{feature} = $sub;
90 my $compat_version = $registry->{$package};
92 my $deprecated_at = $deprecated_at->{ $args{feature} };
95 if defined $compat_version
96 && defined $deprecated_at
97 && $compat_version lt $deprecated_at;
100 if ( defined $args{message} ) {
101 $msg = $args{message};
104 $msg = "$args{feature} has been deprecated";
105 $msg .= " since version $deprecated_at"
106 if defined $deprecated_at;
109 return if $warned{$package}{ $args{feature} }{$msg};
111 $warned{$package}{ $args{feature} }{$msg} = 1;
113 local $Carp::CarpLevel = $Carp::CarpLevel + 1 + $skipped;
121 # ABSTRACT: Manage deprecation warnings for your distribution
131 use Package::DeprecationManager -deprecations => {
132 'My::Class::foo' => '0.02',
133 'My::Class::bar' => '0.05',
134 'feature-X' => '0.07',
138 deprecated( 'Do not call foo!' );
155 feature => 'feature-X',
160 package Other::Class;
162 use My::Class -api_version => '0.04';
164 My::Class->new()->foo(); # warns
165 My::Class->new()->bar(); # does not warn
166 My::Class->new()->far(); # does not warn again
170 This module allows you to manage a set of deprecations for one or more modules.
172 When you import C<Package::DeprecationManager>, you must provide a set of
173 C<-deprecations> as a hash ref. The keys are "feature" names, and the values
174 are the version when that feature was deprecated.
176 In many cases, you can simply use the fully qualified name of a subroutine or
177 method as the feature name. This works for cases where the whole subroutine is
178 deprecated. However, the feature names can be any string. This is useful if
179 you don't want to deprecate an entire subroutine, just a certain usage.
181 You can also provide an optional array reference in the C<-ignore>
182 parameter. This is a list of package names to ignore when looking at the stack
183 to figure out what code used the deprecated feature. This should be packages
184 in your distribution that can appear on the call stack when a deprecated
187 As part of the import process, C<Package::DeprecationManager> will export two
188 subroutines into its caller. It proves an C<import()> sub for the caller and a
191 The C<import()> sub allows callers of I<your> class to specify an C<-api_version>
192 parameter. If this is supplied, then deprecation warnings are only issued for
193 deprecations for api versions earlier than the one specified.
195 You must call C<deprecated()> sub in each deprecated subroutine. When called,
196 it will issue a warning using C<Carp::cluck()>.
198 The C<deprecated()> sub can be called in several ways. If you do not pass any
199 arguments, it will generate an appropriate warning message. If you pass a
200 single argument, this is used as the warning message.
202 Finally, you can call it with named arguments. Currently, the only allowed
203 names are C<message> and C<feature>. The C<feature> argument should correspond
204 to the feature name passed in the C<-deprecations> hash.
206 If you don't explicitly specify a feature, the C<deprecated()> sub uses
207 C<caller()> to identify its caller, using its fully qualified subroutine name.
209 A given deprecation warning is only issued once for a given package. This
210 module tracks this based on both the feature name I<and> the error message
211 itself. This means that if you provide severaldifferent error messages for the
212 same feature, all of those errors will appear.
216 Please report any bugs or feature requests to
217 C<bug-package-deprecationmanager@rt.cpan.org>, or through the web interface at
218 L<http://rt.cpan.org>. I will be notified, and then you'll automatically be
219 notified of progress on your bug as I make changes.
223 If you'd like to thank me for the work I've done on this module, please
224 consider making a "donation" to me via PayPal. I spend a lot of free time
225 creating free software, and would appreciate any support you'd care to offer.
227 Please note that B<I am not suggesting that you must do this> in order
228 for me to continue working on this particular software. I will
229 continue to do so, inasmuch as I have in the past, for as long as it
232 Similarly, a donation made in this way will probably not make me work on this
233 software much more, unless I get so many donations that I can consider working
234 on free software full time, which seems unlikely at best.
236 To donate, log into PayPal and send money to autarch@urth.org or use the
237 button on this page: L<http://www.urth.org/~autarch/fs-donation.html>
241 The idea for this functionality and some of its implementation was originally
242 created as L<Class::MOP::Deprecated> by Goro Fuji.