Curtis "Ovid" Poe > Devel-Deprecate-0.01 > Devel::Deprecate

Download:
Devel-Deprecate-0.01.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.01   Source  

NAME ^

Devel::Deprecate - Create deprecation schedules in your code

VERSION ^

Version 0.01

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 ^

Many times we find ourselves needing to deprecate code or have a deadline and just don't have time to refactor. Instead of trying to remember about this, posting it to a wiki or sending an email, it's better to have an automatic way to deprecate something. This module allows you to do that and embeds the deprecation directly in the code you wish to deprecate.

As we don't want to break production code, deprecations are only triggered when 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. It takes an even-sized list of key/value pairs. Its function is to spit out a warning (or croak) when deprecation criteria are hit.

Deprecation warnings or failures only occur when running tests (but see "PRODUCTION ENVIRONMENTS" below) and are designed to be extremely noisy (and with a strack trace):

 # 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:

 # 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)

Allowed key/value pairs:

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. Perhaps the deprecation won't even start until a new software package is installed in three months and it's 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 our of developers with verbose error messages. Of course, that's the point. The deprecation period, however, should be carefully thought you. 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 will be be triggered unless this condition holds.

AUTHOR ^

Curtis "Ovid" Poe, <ovid at cpan.org>

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.

SUPPORT ^

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

    perldoc Devel::Deprecate

You can also look for information at:

ACKNOWLEDGEMENTS ^

COPYRIGHT & LICENSE ^

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.

syntax highlighting: