stable - Experimental features made easy, once we know they're stable

       Leon Timmermans <fawaka@gmail.com>

       This software is copyright (c) 2013 by Leon Timmermans.

       This is free software; you can redistribute it and/or modify it under  the  same  terms  as  the  Perl  5
       programming language system itself.

perl v5.40.0                                       2025-01-11                                        stable(3pm)

       The experimental pragma makes it easy to turn on experiments while turning off associated warnings.  You
       should read about it, if you don't already know what it does.

       Seeing "use experimental" in code might be scary.  In fact, it probably should be!  Code that uses
       experimental features might break in the future if the perl development team decides that the experiment
       needs to be altered.  When experiments become stable, because the developers decide they're a success,
       the warnings associated with them go away.  When that happens, they can generally be turned on with "use
       feature".

       This is great, if you are using a version of perl where the feature you want is already stable.  If
       you're using an older perl, though, it might be the case that you want to use an experimental feature
       that still warns, even though there's no risk in using it, because subsequent versions of perl have that
       feature unchanged and now stable.

       Here's an example:  The "postderef" feature was added in perl 5.20.0.  In perl 5.24.0, it was marked
       stable.  Using it would no longer trigger a warning.  The behavior of the feature didn't change between
       5.20.0 and 5.24.0.  That means that it's perfectly safe to use the feature on 5.20 or 5.22, even though
       there's a warning.

       In that case, you could very justifiably add "use experimental 'postderef'" but the casual reader may
       still be worried at seeing that.  The "stable" pragma exists to turn on experimental features only when
       it's known that their behavior in the running perl is their stable behavior.

       If you try to use an experimental feature that isn't stable or available on the running version of perl,
       an exception will be thrown.  You should also take care that you've required the version of "stable" that
       you need!

       If it's not immediately obvious why, here's a bit of explanation:

       •   "stable" comes with perl, starting with perl v5.38.

       •   Imagine that v5.38 adds a feature called "florps".  It will stop being experimental in v5.42.

       •   The  version  of  "stable"  that  comes  with  perl  v5.38 can't know that the florps experiment will
           succeed, so you can't "use stable 'florps'" on the version of stable ships  with  v5.38,  because  it
           can't see the future!

       •   You'll  need to write "use stable 1.234 'florps'" to say that you need version 1.234 of stable, which
           is when florps became known to stable.

       Sure, it's a little weird, but it's worth it!  The documentation  of  this  pragma  will  tell  you  what
       version of "stable" you need to require in order to use various features.  See below.

       At present there are only a few "stable" features:

       •   "bitwise" - stable as of perl 5.22, available via stable 0.031

       •   "isa" - stable as of perl 5.32, available via stable 0.031

       •   "lexical_subs" - stable as of perl 5.22, available via stable 0.031

           Lexical  subroutines  were  actually  added in 5.18, and their design did not change, but significant
           bugs makes them unsafe to use before 5.22.

       •   "postderef" - stable as of perl 5.20, available via stable 0.031

       •   "const_attr" - stable as of perl 5.22, available via stable 0.032

       •   "for_list" - stable as of perl 5.36, available via stable 0.032

       stable - Experimental features made easy, once we know they're stable

       perlexperiment contains more information about experimental features.

               use stable 'lexical_subs', 'bitwise';
               my sub is_odd($value) { $value & 1 }

       version 0.034