|
Packit |
92cec9 |
# NAME
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
Package::DeprecationManager - Manage deprecation warnings for your distribution
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# VERSION
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
version 0.17
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# SYNOPSIS
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
package My::Class;
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
use Package::DeprecationManager -deprecations => {
|
|
Packit |
92cec9 |
'My::Class::foo' => '0.02',
|
|
Packit |
92cec9 |
'My::Class::bar' => '0.05',
|
|
Packit |
92cec9 |
'feature-X' => '0.07',
|
|
Packit |
92cec9 |
};
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
sub foo {
|
|
Packit |
92cec9 |
deprecated( 'Do not call foo!' );
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
...
|
|
Packit |
92cec9 |
}
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
sub bar {
|
|
Packit |
92cec9 |
deprecated();
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
...
|
|
Packit |
92cec9 |
}
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
sub baz {
|
|
Packit |
92cec9 |
my %args = @_;
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
if ( $args{foo} ) {
|
|
Packit |
92cec9 |
deprecated(
|
|
Packit |
92cec9 |
message => ...,
|
|
Packit |
92cec9 |
feature => 'feature-X',
|
|
Packit |
92cec9 |
);
|
|
Packit |
92cec9 |
}
|
|
Packit |
92cec9 |
}
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
package Other::Class;
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
use My::Class -api_version => '0.04';
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
My::Class->new()->foo(); # warns
|
|
Packit |
92cec9 |
My::Class->new()->bar(); # does not warn
|
|
Packit |
92cec9 |
My::Class->new()->bar(); # does not warn again
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# DESCRIPTION
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
This module allows you to manage a set of deprecations for one or more modules.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
When you import `Package::DeprecationManager`, you must provide a set of
|
|
Packit |
92cec9 |
`-deprecations` as a hash ref. The keys are "feature" names, and the values
|
|
Packit |
92cec9 |
are the version when that feature was deprecated.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
In many cases, you can simply use the fully qualified name of a subroutine or
|
|
Packit |
92cec9 |
method as the feature name. This works for cases where the whole subroutine is
|
|
Packit |
92cec9 |
deprecated. However, the feature names can be any string. This is useful if
|
|
Packit |
92cec9 |
you don't want to deprecate an entire subroutine, just a certain usage.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
You can also provide an optional array reference in the `-ignore`
|
|
Packit |
92cec9 |
parameter.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
The values to be ignored can be package names or regular expressions (made
|
|
Packit |
92cec9 |
with `qr//`). Use this to ignore packages in your distribution that can
|
|
Packit |
92cec9 |
appear on the call stack when a deprecated feature is used.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
As part of the import process, `Package::DeprecationManager` will export two
|
|
Packit |
92cec9 |
subroutines into its caller. It provides an `import()` sub for the caller and a
|
|
Packit |
92cec9 |
`deprecated()` sub.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
The `import()` sub allows callers of _your_ class to specify an `-api_version`
|
|
Packit |
92cec9 |
parameter. If this is supplied, then deprecation warnings are only issued for
|
|
Packit |
92cec9 |
deprecations with API versions earlier than the one specified.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
You must call the `deprecated()` sub in each deprecated subroutine. When
|
|
Packit |
92cec9 |
called, it will issue a warning using `Carp::cluck()`.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
The `deprecated()` sub can be called in several ways. If you do not pass any
|
|
Packit |
92cec9 |
arguments, it will generate an appropriate warning message. If you pass a
|
|
Packit |
92cec9 |
single argument, this is used as the warning message.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
Finally, you can call it with named arguments. Currently, the only allowed
|
|
Packit |
92cec9 |
names are `message` and `feature`. The `feature` argument should correspond
|
|
Packit |
92cec9 |
to the feature name passed in the `-deprecations` hash.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
If you don't explicitly specify a feature, the `deprecated()` sub uses
|
|
Packit |
92cec9 |
`caller()` to identify its caller, using its fully qualified subroutine name.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
A given deprecation warning is only issued once for a given package. This
|
|
Packit |
92cec9 |
module tracks this based on both the feature name _and_ the error message
|
|
Packit |
92cec9 |
itself. This means that if you provide several different error messages for
|
|
Packit |
92cec9 |
the same feature, all of those errors will appear.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
## Other import() subs
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
This module works by installing an `import` sub in any package that uses
|
|
Packit |
92cec9 |
it. If that package _already_ has an `import` sub, then that `import` will
|
|
Packit |
92cec9 |
be called after any arguments passed for `Package::DeprecationManager` are
|
|
Packit |
92cec9 |
stripped out. You need to define your `import` sub before you `use
|
|
Packit |
92cec9 |
Package::DeprecationManager` to make this work:
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
package HasExporter;
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
use Exporter qw( import );
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
use Package::DeprecationManager -deprecations => {
|
|
Packit |
92cec9 |
'HasExporter::foo' => '0.02',
|
|
Packit |
92cec9 |
};
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
our @EXPORT_OK = qw( some_sub another_sub );
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# DONATIONS
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
If you'd like to thank me for the work I've done on this module, please
|
|
Packit |
92cec9 |
consider making a "donation" to me via PayPal. I spend a lot of free time
|
|
Packit |
92cec9 |
creating free software, and would appreciate any support you'd care to offer.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
Please note that **I am not suggesting that you must do this** in order
|
|
Packit |
92cec9 |
for me to continue working on this particular software. I will
|
|
Packit |
92cec9 |
continue to do so, inasmuch as I have in the past, for as long as it
|
|
Packit |
92cec9 |
interests me.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
Similarly, a donation made in this way will probably not make me work on this
|
|
Packit |
92cec9 |
software much more, unless I get so many donations that I can consider working
|
|
Packit |
92cec9 |
on free software full time, which seems unlikely at best.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
To donate, log into PayPal and send money to autarch@urth.org or use the
|
|
Packit |
92cec9 |
button on this page: [http://www.urth.org/~autarch/fs-donation.html](http://www.urth.org/~autarch/fs-donation.html)
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# CREDITS
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
The idea for this functionality and some of its implementation was originally
|
|
Packit |
92cec9 |
created as [Class::MOP::Deprecated](https://metacpan.org/pod/Class::MOP::Deprecated) by Goro Fuji.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# BUGS
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
Please report any bugs or feature requests to
|
|
Packit |
92cec9 |
`bug-package-deprecationmanager@rt.cpan.org`, or through the web interface at
|
|
Packit |
92cec9 |
[http://rt.cpan.org](http://rt.cpan.org). I will be notified, and then you'll automatically be
|
|
Packit |
92cec9 |
notified of progress on your bug as I make changes.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
Bugs may be submitted through [the RT bug tracker](http://rt.cpan.org/Public/Dist/Display.html?Name=Package-DeprecationManager)
|
|
Packit |
92cec9 |
(or [bug-package-deprecationmanager@rt.cpan.org](mailto:bug-package-deprecationmanager@rt.cpan.org)).
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
I am also usually active on IRC as 'drolsky' on `irc://irc.perl.org`.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# DONATIONS
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
If you'd like to thank me for the work I've done on this module, please
|
|
Packit |
92cec9 |
consider making a "donation" to me via PayPal. I spend a lot of free time
|
|
Packit |
92cec9 |
creating free software, and would appreciate any support you'd care to offer.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
Please note that **I am not suggesting that you must do this** in order for me
|
|
Packit |
92cec9 |
to continue working on this particular software. I will continue to do so,
|
|
Packit |
92cec9 |
inasmuch as I have in the past, for as long as it interests me.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
Similarly, a donation made in this way will probably not make me work on this
|
|
Packit |
92cec9 |
software much more, unless I get so many donations that I can consider working
|
|
Packit |
92cec9 |
on free software full time (let's all have a chuckle at that together).
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
To donate, log into PayPal and send money to autarch@urth.org, or use the
|
|
Packit |
92cec9 |
button at [http://www.urth.org/~autarch/fs-donation.html](http://www.urth.org/~autarch/fs-donation.html).
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# AUTHOR
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
Dave Rolsky <autarch@urth.org>
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# CONTRIBUTORS
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
- Jesse Luehrs <doy@tozt.net>
|
|
Packit |
92cec9 |
- Karen Etheridge <ether@cpan.org>
|
|
Packit |
92cec9 |
- Tomas Doran <bobtfish@bobtfish.net>
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
# COPYRIGHT AND LICENCE
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
This software is Copyright (c) 2016 by Dave Rolsky.
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
This is free software, licensed under:
|
|
Packit |
92cec9 |
|
|
Packit |
92cec9 |
The Artistic License 2.0 (GPL Compatible)
|