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;
99 return if $warned{$package}{ $args{feature} };
102 if ( defined $args{message} ) {
103 $msg = $args{message};
106 $msg = "$args{feature} has been deprecated";
107 $msg .= " since version $deprecated_at"
108 if defined $deprecated_at;
111 $warned{$package}{ $args{feature} } = 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 Deprecation warnings are only issued once for a given package, regardless of
210 how many times the deprecated sub/method is called.
214 Please report any bugs or feature requests to
215 C<bug-package-deprecationmanager@rt.cpan.org>, or through the web interface at
216 L<http://rt.cpan.org>. I will be notified, and then you'll automatically be
217 notified of progress on your bug as I make changes.
221 If you'd like to thank me for the work I've done on this module, please
222 consider making a "donation" to me via PayPal. I spend a lot of free time
223 creating free software, and would appreciate any support you'd care to offer.
225 Please note that B<I am not suggesting that you must do this> in order
226 for me to continue working on this particular software. I will
227 continue to do so, inasmuch as I have in the past, for as long as it
230 Similarly, a donation made in this way will probably not make me work on this
231 software much more, unless I get so many donations that I can consider working
232 on free software full time, which seems unlikely at best.
234 To donate, log into PayPal and send money to autarch@urth.org or use the
235 button on this page: L<http://www.urth.org/~autarch/fs-donation.html>
239 The idea for this functionality and some of its implementation was originally
240 created as L<Class::MOP::Deprecated> by Goro Fuji.