1package stable; 2$stable::VERSION = '0.033'; 3use strict; 4use warnings; 5use version (); 6 7use experimental (); 8use Carp qw/croak carp/; 9 10my %allow_at = ( 11 bitwise => 5.022000, 12 isa => 5.032000, 13 lexical_subs => 5.022000, 14 postderef => 5.020000, 15 const_attr => 5.022000, 16 for_list => 5.036000, 17); 18 19sub import { 20 my ($self, @pragmas) = @_; 21 22 for my $pragma (@pragmas) { 23 my $min_ver = $allow_at{$pragma}; 24 croak "unknown stablized experiment $pragma" unless defined $min_ver; 25 croak "requested stablized experiment $pragma, which is stable at $min_ver but this is $]" 26 unless $] >= $min_ver; 27 } 28 29 experimental->import(@pragmas); 30 return; 31} 32 33sub unimport { 34 my ($self, @pragmas) = @_; 35 36 # Look, we could say "You can't unimport stable experiment 'bitwise' on 37 # 5.20" but it just seems weird. -- rjbs, 2022-03-05 38 experimental->unimport(@pragmas); 39 return; 40} 41 421; 43 44#ABSTRACT: Experimental features made easy, once we know they're stable 45 46__END__ 47 48=pod 49 50=encoding UTF-8 51 52=head1 NAME 53 54stable - Experimental features made easy, once we know they're stable 55 56=head1 VERSION 57 58version 0.032 59 60=head1 SYNOPSIS 61 62 use stable 'lexical_subs', 'bitwise'; 63 my sub is_odd($value) { $value & 1 } 64 65=head1 DESCRIPTION 66 67The L<experimental> pragma makes it easy to turn on experiments while turning 68off associated warnings. You should read about it, if you don't already know 69what it does. 70 71Seeing C<use experimental> in code might be scary. In fact, it probably should 72be! Code that uses experimental features might break in the future if the perl 73development team decides that the experiment needs to be altered. When 74experiments become stable, because the developers decide they're a success, the 75warnings associated with them go away. When that happens, they can generally 76be turned on with C<use feature>. 77 78This is great, if you are using a version of perl where the feature you want is 79already stable. If you're using an older perl, though, it might be the case 80that you want to use an experimental feature that still warns, even though 81there's no risk in using it, because subsequent versions of perl have that 82feature unchanged and now stable. 83 84Here's an example: The C<postderef> feature was added in perl 5.20.0. In perl 855.24.0, it was marked stable. Using it would no longer trigger a warning. The 86behavior of the feature didn't change between 5.20.0 and 5.24.0. That means 87that it's perfectly safe to use the feature on 5.20 or 5.22, even though 88there's a warning. 89 90In that case, you could very justifiably add C<use experimental 'postderef'> 91but the casual reader may still be worried at seeing that. The C<stable> 92pragma exists to turn on experimental features only when it's known that 93their behavior in the running perl is their stable behavior. 94 95If you try to use an experimental feature that isn't stable or available on 96the running version of perl, an exception will be thrown. You should also take 97care that you've required the version of C<stable> that you need! 98 99If it's not immediately obvious why, here's a bit of explanation: 100 101=over 4 102 103=item * 104 105C<stable> comes with perl, starting with perl v5.38. 106 107=item * 108 109Imagine that v5.38 adds a feature called "florps". It will stop being 110experimental in v5.42. 111 112=item * 113 114The version of C<stable> that comes with perl v5.38 can't know that the 115I<florps> experiment will succeed, so you can't C<use stable 'florps'> on the 116version of stable ships with v5.38, because it can't see the future! 117 118=item * 119 120You'll need to write C<use stable 1.234 'florps'> to say that you need version 1211.234 of stable, which is when I<florps> became known to stable. 122 123=back 124 125Sure, it's a little weird, but it's worth it! The documentation of this pragma 126will tell you what version of C<stable> you need to require in order to use 127various features. See below. 128 129At present there are only a few "stable" features: 130 131=over 4 132 133=item * C<bitwise> - stable as of perl 5.22, available via stable 0.031 134 135=item * C<isa> - stable as of perl 5.32, available via stable 0.031 136 137=item * C<lexical_subs> - stable as of perl 5.22, available via stable 0.031 138 139Lexical subroutines were actually added in 5.18, and their design did not 140change, but significant bugs makes them unsafe to use before 5.22. 141 142=item * C<postderef> - stable as of perl 5.20, available via stable 0.031 143 144=item * C<const_attr> - stable as of perl 5.22, available via stable 0.032 145 146=item * C<for_list> - stable as of perl 5.36, available via stable 0.032 147 148=back 149 150=head1 SEE ALSO 151 152L<perlexperiment|perlexperiment> contains more information about experimental features. 153 154=head1 AUTHOR 155 156Leon Timmermans <leont@cpan.org> 157 158=head1 COPYRIGHT AND LICENSE 159 160This software is copyright (c) 2013 by Leon Timmermans. 161 162This is free software; you can redistribute it and/or modify it under 163the same terms as the Perl 5 programming language system itself. 164 165=cut 166