6 # our %Config can ignore %Config::Config, e.g. for testing
8 unless (%Config) { require Config; *Config = \%Config::Config; }
10 # This isn't a public API. It's internal to code maintained by the perl-porters
11 # If you would like it to be a public API, please send a patch with
12 # documentation and tests. Until then, it may change without warning.
13 sub __loaded_from_core {
14 my ($package, $file, $expect_leaf) = @_;
16 foreach my $pair ([qw(sitearchexp archlibexp)],
17 [qw(sitelibexp privlibexp)]) {
18 my ($site, $priv) = @Config{@$pair};
20 for my $d ($site, $priv) { $d = VMS::Filespec::unixify($d) };
22 # Just in case anyone managed to configure with trailing /s
23 s!/*$!!g foreach $site, $priv;
25 next if $site eq $priv;
26 if (uc("$priv/$expect_leaf") eq uc($file)) {
34 my ($package, $file) = caller;
36 my $expect_leaf = "$package.pm";
37 $expect_leaf =~ s!::!/!g;
39 if (__loaded_from_core($package, $file, $expect_leaf)) {
42 while (@caller = caller $call_depth++) {
43 last if $caller[7] # use/require
44 and $caller[6] eq $expect_leaf; # the package file
49 Can't find use/require $expect_leaf in caller stack
54 # This is fragile, because it
55 # is directly poking in the internals of warnings.pm
56 my ($call_file, $call_line, $callers_bitmask) = @caller[1,2,9];
58 if (defined $callers_bitmask
59 && (vec($callers_bitmask, $warnings::Offsets{deprecated}, 1)
60 || vec($callers_bitmask, $warnings::Offsets{all}, 1))) {
62 $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.
74 deprecate - Perl pragma for deprecating the inclusion of a module in core
78 use deprecate; # warn about future absence if loaded from core
83 This pragma simplifies the maintenance of dual-life modules that will no longer
84 be included in the Perl core in a future Perl release, but are still included
87 The purpose of the pragma is to alert users to the status of such a module by
88 issuing a warning that encourages them to install the module from CPAN, so that
89 a future upgrade to a perl which omits the module will not break their code.
91 This warning will only be issued if the module was loaded from a core library
92 directory, which allows the C<use deprecate> line to be included in the CPAN
93 version of the module. Because the pragma remains silent when the module is run
94 from a non-core library directory, the pragma call does not need to be patched
95 into or out of either the core or CPAN version of the module. The exact same
96 code can be shipped for either purpose.
98 =head2 Important Caveat
100 Note that when a module installs from CPAN to a core library directory rather
101 than the site library directories, the user gains no protection from having
104 At the same time, this pragma cannot detect when such a module has installed
105 from CPAN to the core library, and so it would endlessly and uselessly exhort
108 Therefore modules that can install from CPAN to the core library must make sure
109 not to call this pragma when they have done so. Generally this means that the
110 exact logic from the installer must be mirrored inside the module. E.g.:
115 INSTALLDIRS => ( "$]" >= 5.011 ? 'site' : 'perl' ),
119 use if "$]" >= 5.011, 'deprecate';
121 (The above example shows the most important case of this: when the target is
122 a Perl older than 5.12 (where the core library directories take precedence over
123 the site library directories) and the module being installed was included in
124 core in that Perl version. Under those circumstances, an upgrade of the module
125 from CPAN is only possible by installing to the core library.)
130 None by default. The only method is C<import>, called by C<use deprecate;>.
135 First example to C<use deprecate;> was L<Switch>.
140 Original version by Nicholas Clark
143 =head1 COPYRIGHT AND LICENSE
145 Copyright (C) 2009, 2011
147 This library is free software; you can redistribute it and/or modify
148 it under the same terms as Perl itself, either Perl version 5.10.0 or,
149 at your option, any later version of Perl 5 you may have available.