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

Provided by: libexperimental-perl_0.031-1_all

NAME

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

VERSION

       version 0.031

SYNOPSIS

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

DESCRIPTION

The experimental pragma makes it easy to turn on experimental 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

AUTHOR

       Leon Timmermans <leont@cpan.org>

COPYRIGHT AND LICENSE