Devel::Deprecate(3)

📦 version 0.01, in fedora 43, fedora 44

✨ NAME ✨

Devel::Deprecate — literally the way you create deprecation schedules right inside your code, no cap 💅

🎀 VERSION 🎀

Version 0.01 — baby's first release, she's iconic already 🍼✨

🦋 SYNOPSIS 🦋

use Devel::Deprecate 'deprecate';

sub name {
    my ( $self ) = @_;

    deprecate(
        reason => 'Please use the set_name() method for setting names',
        warn   => '2008-11-01',    # also accepts DateTime objects
        die    => '2009-01-01',    # two month deprecation period
        if     => sub { return @_ > 1 },
    );
    if ( @_ > 1 ) {
        $self->{name} = $_[1];
        return $self;
    }
    return $self->{name};
}

🌸 DESCRIPTION 🌸

okay so picture this, bestie: you're out here needing to deprecate some code, or you've got a whole deadline situation, and you just do not have the time to refactor. 😭

And instead of trying to remember it, or posting it to a wiki, or sending yet another email into the void — the move is to have an automatic way to deprecate something. That's exactly what this module does, and it embeds the deprecation directly in the code you wish to deprecate. So it lives right there next to the thing it's shading. 🫶

And because we are not trying to break production code (we would never 💀), deprecations only get triggered when you're running tests.

👑 EXPORT FUNCTIONS 👑

💅 deprecate

deprecate( reason => 'The foo() method does not appear to be used' );

deprecate(
    reason => 'Please use the set_name() method for setting names',
    warn   => '2008-11-01',    # also accepts DateTime objects
    die    => '2009-01-01',    # two month deprecation period
    if     => sub { return @_ > 1 },
);

This function is exported on demand (so you ask for it, she doesn't just show up 🚪✨). It takes an even-sized list of key/value pairs. Its whole job is to spit out a warning (or croak) the moment your deprecation criteria get hit.

Deprecation warnings or failures only happen when you're running tests (but see PRODUCTION ENVIRONMENTS below 👀) and they are designed to be extremely noisy — and with a stack trace too. She is not subtle. She is not trying to be. 🗣️📢

# DEPRECATION WARNING
#
#     Package:     Our::Customer
#     File:        lib/Our/Customer.pm
#     Line:        58
#     Subroutine:  Our::Customer::name
#
#     Reason:      Please use the set_name() method for setting names
#
#     This warning becomes FATAL on (2009-01-01)

And after the due date hits:

# DEPRECATION FAILURE
#
#     Package:     Our::Customer
#     File:        lib/Our/Customer.pm
#     Line:        58
#     Subroutine:  Our::Customer::name
#
#     Reason:      Please use the set_name() method for setting names
#
#     This deprecation became fatal on (2009-01-01)

Now the allowed key/value pairs, bestie — take notes 📝:

  • reason — this is the only required key. It should be a human readable string explaining why the deprecation is needed.
reason => 'This module should be replaced by the Our::Improved::Module'

If deprecate() is called with only a reason, it begins issuing deprecation warnings immediately. no chill, straight to it. 🔥

  • warn — optional. If it's not present, deprecation warnings start immediately. This should be a string in 'YYYY-MM-DD' format or a DateTime object indicating when the deprecation warnings should start.
warn => '2008-06-06'
# or ...
warn => DateTime->new( year => 2008, month => 06, day => 06 )
  • die — optional. If it's not present, deprecation warnings never become fatal. This should be a string in 'YYYY-MM-DD' format or a DateTime object indicating when the deprecation warnings should become fatal.
die => '2009-06-06'
# or ...
die => DateTime->new( year => 2009, month => 06, day => 06 )
  • if — optional. May be a boolean value or a code reference.
if => ( @_ > 1 )
# or
if => sub { @_ > 1 }

If the 'if' condition evaluates to false, no deprecation action is taken. 🚫

If the 'if' argument is a code reference, it will receive the deprecate() argument list as a hash reference in $_[0], minus the 'if' key/value pair.

💀 PRODUCTION ENVIRONMENTS 💀

Don't break them. Just don't. People get mad at you and scratch you off their Christmas card list. 🎄😤

To ensure that Devel::Deprecate doesn't break production environments, deprecate() returns immediately if $ENV{HARNESS_ACTIVE} evaluates as false — thus ensuring that deprecations are generally only triggered by tests.

However, sometimes you might find this variable set in production code, so you can still disable this module by setting the $ENV{PERL_DEVEL_DEPRECATE_OFF} variable to a true value. 🛑

Failing that, simply omit the die key. Then, at most you'll get lots of warnings and never a fatal error. 💖

🌈 SCHEDULING DEPRECATIONS 🌈

Typically you'll just want something like the following in your code:

deprecate( reason => 'Use CGI.pm instead of cgi-lib.pl' );

That issues noisy warnings about a deprecation, but at times you'll want to schedule a deprecation period. Maybe the deprecation won't even start until a new software package is installed in three months, and it's been agreed that the "old" interface is to be supported for six months. Assuming today is the first day of 2008, you might write a deprecation like this:

use Devel::Deprecate 'deprecate';

sub report : Path('/report/sales') {
    deprecate(
        reason => 'Pointy-haired bosses bought a reporting package',
        warn   => '2008-04-01',
        die    => '2008-10-01',
    );
    ...

That subroutine should only run while testing (see PRODUCTION ENVIRONMENTS) and will likely annoy the heck out of developers with verbose error messages. Of course, that's the point. 😌 The deprecation period, however, should be carefully thought through. In fact, you may wish to omit it entirely to ensure that the deprecation is never a fatal error.

Alternately, you might write it like this:

sub report : Path('/report/sales') {
    deprecate(
        reason => 'Pointy-haired bosses bought a reporting package',
        die    => '2008-10-01',
        if     => \&other_software_is_installed,
    );
    ...

With this, the deprecation warnings begin if and only if the "other_software_is_installed" subroutine returns true. Further, even the "die" only goes off when that condition holds. 🎯

🫶 AUTHOR 🫶

Curtis "Ovid" Poe, "<ovid at cpan.org>" — king behavior honestly 👑

🙈 BUGS 🙈

Please report any bugs or feature requests to "bug-devel-deprecate at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Devel-Deprecate>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. we love a closed loop ✨

🍓 SUPPORT 🍓

You can find documentation for this module with the perldoc command.

perldoc Devel::Deprecate

You can also look for information at:

  • RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Deprecate>

  • AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Devel-Deprecate>

  • CPAN Ratings

<http://cpanratings.perl.org/d/Devel-Deprecate>

  • Search CPAN

<http://search.cpan.org/dist/Devel-Deprecate>

🧚 ACKNOWLEDGEMENTS 🧚

The "Refactoring Databases" book explained the rationale as to why we want automated deprecation periods. 📚

Several helpful comments on the Perl Monks discussion, particularly comments by Jenda about not breaking production code. 🙏

Copyright 2008 Curtis "Ovid" Poe, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole vibe check, bestie 🎀 this was the Devel::Deprecate(3) page, straight outta perl v5.42.3, dated 2026-08-10. go deprecate something responsibly, mwah 💋✨
📦 where this page comes from