The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Devel-Deprecations-Environmental-1.101
River stage two • 1 direct dependent • 19 total dependents
1 ++
/ Devel::Deprecations::Environmental

NAME

Devel::Deprecations::Environmental - deprecations for your code's surroundings

DESCRIPTION

A framework for managing deprecations of the environment in which your code runs

SYNOPSIS

This will load the Devel::Deprecations::Environmental::Plugin::Int32 plugin and emit a warning if running on a 32 bit system:

    use Devel::Deprecations::Environmental qw(Int32);

This will start warning about an impending deprecation on the 1st of February 2023, upgrade that to a warning about being unsupported on the 1st of February 2024, and upgrade that to a fatal error on the 1st of February 2025:

    use Devel::Deprecations::Environmental
        Int32 => {
            warn_from        => '2023-02-01',
            unsupported_from => '2024-02-01',
            fatal_from       => '2025-02-01',
        };

This will always warn about 32 bit perl or a really old perl:

    use Devel::Deprecations::Environmental
        OldPerl => { older_than => '5.14.0', },
        'Int32';

INCOMPATIBLE CHANGES

Version 1.000 used DateTime::Format::ISO8601 for parsing times provided as strings. This was removed in 1.100 as it had an unreasonable number of dependencies. As a result we now only support a subset of ISO 8601 formats, namely the sensible ones:

YYYY-MM-DD
YYYY-MM-DD HH:MM:SS
YYYY-MM-DDTHH:MM:SS

You can still pass in a DateTime object if you wish, and so can use DateTime::Format::ISO8601 yourself to construct them from some crazy involving week numbers if you really want.

DEPRECATION ARGUMENTS

Each deprecation has a name, which can be optionally followed by a hash-ref of arguments. All deprecations automatically support:

warn_from

The time at which to start emitting warnings about an impending deprecation. Defaults to the moment of creation, '1970-01-01' (in general the accepted date format is YYYY-MM-DD followed by an optional space or letter T and HH:MM:SS). You can also provide this as a DateTime object.

This must be before any of unsupported_from or fatal_from which are specified.

unsupported_from

The time at which to start warning harder, when something is no longer supported. Defaults to undef, meaning "don't do this".

This must be before fatal_from if that is specified.

fatal_from

The time after which the code should just die. Defaults to undef, meaning "don't do this".

Of those three only the most severe will be emitted.

Arguments with names beginning with an underscore are reserved for internal use. Plugins can support any other arguments they wish.

CONTENT OF WARNINGS / FATAL ERRORS

The pseudo-variables $date, $filename, $line, and $reason will be interpolated.

$date will be From $unsupported_from: or From $fatal_from: (using whichever is earlier) if one of those is configured.

$filename and $line will tell you the file and line on which Devel::Deprecations::Environmental is loaded.

$reason is defined in the plugin's reason() method.

Initial warning

Deprecation warning! ${date}In $filename on line $line: $reason\n

"Unsupported" warning

Unsupported! In $filename on line $line: $reason\n

Fatal error

Unsupported! In $filename on line $line: $reason\n

FUNCTIONS

There are no public functions or methods, everything is done when the module is loaded (specifically, when its import() method is called) with all specific deprecations handled by plugins.

WRITING YOUR OWN PLUGINS

The Devel::Deprecations::Environmental::Plugin::* namespace is yours to play in, except for the Devel::Deprecations::Environmental::Plugin::Internal::* namespace.

A plugin should inherit from Devel::Deprecation, and implement the following methods, which will be called as class methods. Failure to define either of them will result in fatal errors. They will be passed the arguments hash-ref (with warn_from, unsupported_from, and fatal_from removed):

reason

Returns a brief string explaining the deprecation. For example "32 bit integers" or "Perl too old".

is_deprecated

This should return true or false for whether the environment matches the deprecation or not.

FEEDBACK

I welcome feedback about my code, including constructive criticism, bug reports, documentation improvements, and feature requests. The best bug reports include files that I can add to the test suite, which fail with the current code in my git repo and will pass once I've fixed the bug

Feature requests are far more likely to get implemented if you submit a patch yourself, preferably with tests.

SOURCE CODE REPOSITORY

git://github.com/DrHyde/perl-modules-Devel-Deprecations.git

SEE ALSO

Devel::Deprecate - for deprecating parts of your own code as opposed to parts of the environment your code is running in;

AUTHOR, LICENCE and COPYRIGHT

Copyright 2023 David Cantrell <david@cantrell.org.uk>

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

CONSPIRACY

This module is also free-as-in-mason software.