1stable(3)             User Contributed Perl Documentation            stable(3)
2
3
4

NAME

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

VERSION

9       version 0.031
10

SYNOPSIS

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

DESCRIPTION

16       The experimental pragma makes it easy to turn on experimental while
17       turning off associated warnings.  You should read about it, if you
18       don't already know what it does.
19
20       Seeing "use experimental" in code might be scary.  In fact, it probably
21       should be!  Code that uses experimental features might break in the
22       future if the perl development team decides that the experiment needs
23       to be altered.  When experiments become stable, because the developers
24       decide they're a success, the warnings associated with them go away.
25       When that happens, they can generally be turned on with "use feature".
26
27       This is great, if you are using a version of perl where the feature you
28       want is already stable.  If you're using an older perl, though, it
29       might be the case that you want to use an experimental feature that
30       still warns, even though there's no risk in using it, because
31       subsequent versions of perl have that feature unchanged and now stable.
32
33       Here's an example:  The "postderef" feature was added in perl 5.20.0.
34       In perl 5.24.0, it was marked stable.  Using it would no longer trigger
35       a warning.  The behavior of the feature didn't change between 5.20.0
36       and 5.24.0.  That means that it's perfectly safe to use the feature on
37       5.20 or 5.22, even though there's a warning.
38
39       In that case, you could very justifiably add "use experimental
40       'postderef'" but the casual reader may still be worried at seeing that.
41       The "stable" pragma exists to turn on experimental features only when
42       it's known that their behavior in the running perl is their stable
43       behavior.
44
45       If you try to use an experimental feature that isn't stable or
46       available on the running version of perl, an exception will be thrown.
47       You should also take care that you've required the version of "stable"
48       that you need!
49
50       If it's not immediately obvious why, here's a bit of explanation:
51
52       •   "stable" comes with perl, starting with perl v5.38.
53
54       •   Imagine that v5.38 adds a feature called "florps".  It will stop
55           being experimental in v5.42.
56
57       •   The version of "stable" that comes with perl v5.38 can't know that
58           the florps experiment will succeed, so you can't "use stable
59           'florps'" on the version of stable ships with v5.38, because it
60           can't see the future!
61
62       •   You'll need to write "use stable 1.234 'florps'" to say that you
63           need version 1.234 of stable, which is when florps became known to
64           stable.
65
66       Sure, it's a little weird, but it's worth it!  The documentation of
67       this pragma will tell you what version of "stable" you need to require
68       in order to use various features.  See below.
69
70       At present there are only a few "stable" features:
71
72       •   "bitwise" - stable as of perl 5.22, available via stable 0.031
73
74       •   "isa" - stable as of perl 5.32, available via stable 0.031
75
76       •   "lexical_subs" - stable as of perl 5.22, available via stable 0.031
77
78           Lexical subroutines were actually added in 5.18, and their design
79           did not change, but significant bugs makes them unsafe to use
80           before 5.22.
81
82       •   "postderef" - stable as of perl 5.20, available via stable 0.031
83

SEE ALSO

85       perlexperiment contains more information about experimental features.
86

AUTHOR

88       Leon Timmermans <leont@cpan.org>
89
91       This software is copyright (c) 2013 by Leon Timmermans.
92
93       This is free software; you can redistribute it and/or modify it under
94       the same terms as the Perl 5 programming language system itself.
95
96
97
98perl v5.38.0                      2023-07-21                         stable(3)
Impressum