stable(3perl)

💖 stable 💖

okay bestie, so picture this: a manual page that's literally called stable — for Perl — and it's all about "Experimental features made easy, once we know they're stable" ✨ (that's the NAME section, we're folding it in up top like the little crown it is 👑). Manual name? stable, section 3perl. Perl Programmers Reference Guide. Slay.

✨ VERSION ✨

version 0.036 🎀

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

So there's this thing called the experimental pragma 💅 and what it does is make it easy to turn experiments on while turning the associated warnings off. If you don't already know what it does, bestie, go read about it, fr fr.

Now. Seeing use experimental in code? Might be scary. And honestly it probably should be! 😭 Code that uses experimental features might break later if the perl dev team decides an experiment needs to be altered. But when experiments become stable — because the developers decide they're a success 🌈 — the warnings attached to them go away. And when that happens, you can generally turn them on with use feature.

Which is great!! 🫶 IF you're on a version of perl where the feature you want is already stable. But if you're on an older perl, here's the lil dilemma: you might want to use an experimental feature that still warns, even though there's literally zero risk in using it, because later versions of perl have that feature unchanged and now stable. 🙈

Example time, because examples are the moment 💫:

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. And the behavior of the feature didn't change between 5.20.0 and 5.24.0. Which means it's perfectly safe to use the feature on 5.20 or 5.22, even though there's a warning.

So in that case you could very justifiably write use experimental 'postderef' — but the casual reader may still be worried when they see that 😬. Which is exactly why 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. iconic tbh.

And listen — if you try to use an experimental feature that isn't stable or isn't available on the running version of perl, an exception will be thrown 💀. 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

👀 SEE ALSO 👀

perlexperiment contains more information about experimental features. go peek, bestie 🍓

🧚 AUTHOR 🧚

Leon Timmermans <fawaka@gmail.com>

💜 COPYRIGHT AND LICENSE 💜

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.

---

and that's the whole page, periodt 💅 this is perl v5.44.0, dated 2026-10-17, and yes you read that right — stable(3perl). no cap, go use your stable features responsibly, mwah 🎀💖