package deprecate; use strict; use warnings; our $VERSION = 0.02; # our %Config can ignore %Config::Config, e.g. for testing our %Config; unless (%Config) { require Config; *Config = \%Config::Config; } # This isn't a public API. It's internal to code maintained by the perl-porters # If you would like it to be a public API, please send a patch with # documentation and tests. Until then, it may change without warning. sub __loaded_from_core { my ($package, $file, $expect_leaf) = @_; foreach my $pair ([qw(sitearchexp archlibexp)], [qw(sitelibexp privlibexp)]) { my ($site, $priv) = @Config{@$pair}; if ($^O eq 'VMS') { for my $d ($site, $priv) { $d = VMS::Filespec::unixify($d) }; } # Just in case anyone managed to configure with trailing /s s!/*$!!g foreach $site, $priv; next if $site eq $priv; if (uc("$priv/$expect_leaf") eq uc($file)) { return 1; } } return 0; } sub import { my ($package, $file) = caller; my $expect_leaf = "$package.pm"; $expect_leaf =~ s!::!/!g; if (__loaded_from_core($package, $file, $expect_leaf)) { my $call_depth=1; my @caller; while (@caller = caller $call_depth++) { last if $caller[7] # use/require and $caller[6] eq $expect_leaf; # the package file } unless (@caller) { require Carp; Carp::cluck(<<"EOM"); Can't find use/require $expect_leaf in caller stack EOM return; } # This is fragile, because it # is directly poking in the internals of warnings.pm my ($call_file, $call_line, $callers_bitmask) = @caller[1,2,9]; if (defined $callers_bitmask && (vec($callers_bitmask, $warnings::Offsets{deprecated}, 1) || vec($callers_bitmask, $warnings::Offsets{all}, 1))) { warn <<"EOM"; $package will be removed from the Perl core distribution in the next major release. Please install it from CPAN. It is being used at $call_file, line $call_line. EOM } } } 1; __END__ =head1 NAME deprecate - Perl pragma for deprecating the core version of a module =head1 SYNOPSIS use deprecate; # always deprecate the module in which this occurs use if $] > 5.010, 'deprecate'; # conditionally deprecate the module =head1 DESCRIPTION This module is used using C (or something that calls C<< deprecate->import() >>, for example C). If the module that includes C is located in a core library directory, a deprecation warning is issued, encouraging the user to use the version on CPAN. If that module is located in a site library, it is the CPAN version, and no warning is issued. =head2 EXPORT None by default. The only method is C, called by C. =head1 SEE ALSO First example to C was L. =head1 AUTHOR Original version by Nicholas Clark =head1 COPYRIGHT AND LICENSE Copyright (C) 2009, 2011 This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available. =cut