Debian Codegraph @

upstream/debian-unstable/man3/stable.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "stable 3perl"
58 .TH stable 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 stable \- Experimental features made easy, once we know they're stable
65 .SH VERSION
66 .IX Header "VERSION"
67 version 0.032
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& use stable \*(Aqlexical_subs\*(Aq, \*(Aqbitwise\*(Aq;
72 \& my sub is_odd($value) { $value & 1 }
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 The experimental pragma makes it easy to turn on experiments while turning
77 off associated warnings. You should read about it, if you don't already know
78 what it does.
79 .PP
80 Seeing \f(CW\*(C`use experimental\*(C'\fR in code might be scary. In fact, it probably should
81 be! Code that uses experimental features might break in the future if the perl
82 development team decides that the experiment needs to be altered. When
83 experiments become stable, because the developers decide they're a success, the
84 warnings associated with them go away. When that happens, they can generally
85 be turned on with \f(CW\*(C`use feature\*(C'\fR.
86 .PP
87 This is great, if you are using a version of perl where the feature you want is
88 already stable. If you're using an older perl, though, it might be the case
89 that you want to use an experimental feature that still warns, even though
90 there's no risk in using it, because subsequent versions of perl have that
91 feature unchanged and now stable.
92 .PP
93 Here's an example: The \f(CW\*(C`postderef\*(C'\fR feature was added in perl 5.20.0. In perl
94 5.24.0, it was marked stable. Using it would no longer trigger a warning. The
95 behavior of the feature didn't change between 5.20.0 and 5.24.0. That means
96 that it's perfectly safe to use the feature on 5.20 or 5.22, even though
97 there's a warning.
98 .PP
99 In that case, you could very justifiably add \f(CW\*(C`use experimental \*(Aqpostderef\*(Aq\*(C'\fR
100 but the casual reader may still be worried at seeing that. The \f(CW\*(C`stable\*(C'\fR
101 pragma exists to turn on experimental features only when it's known that
102 their behavior in the running perl is their stable behavior.
103 .PP
104 If you try to use an experimental feature that isn't stable or available on
105 the running version of perl, an exception will be thrown. You should also take
106 care that you've required the version of \f(CW\*(C`stable\*(C'\fR that you need!
107 .PP
108 If it's not immediately obvious why, here's a bit of explanation:
109 .IP \(bu 4
110 \&\f(CW\*(C`stable\*(C'\fR comes with perl, starting with perl v5.38.
111 .IP \(bu 4
112 Imagine that v5.38 adds a feature called "florps". It will stop being
113 experimental in v5.42.
114 .IP \(bu 4
115 The version of \f(CW\*(C`stable\*(C'\fR that comes with perl v5.38 can't know that the
116 \&\fIflorps\fR experiment will succeed, so you can't \f(CW\*(C`use stable \*(Aqflorps\*(Aq\*(C'\fR on the
117 version of stable ships with v5.38, because it can't see the future!
118 .IP \(bu 4
119 You'll need to write \f(CW\*(C`use stable 1.234 \*(Aqflorps\*(Aq\*(C'\fR to say that you need version
120 1.234 of stable, which is when \fIflorps\fR became known to stable.
121 .PP
122 Sure, it's a little weird, but it's worth it! The documentation of this pragma
123 will tell you what version of \f(CW\*(C`stable\*(C'\fR you need to require in order to use
124 various features. See below.
125 .PP
126 At present there are only a few "stable" features:
127 .IP \(bu 4
128 \&\f(CW\*(C`bitwise\*(C'\fR \- stable as of perl 5.22, available via stable 0.031
129 .IP \(bu 4
130 \&\f(CW\*(C`isa\*(C'\fR \- stable as of perl 5.32, available via stable 0.031
131 .IP \(bu 4
132 \&\f(CW\*(C`lexical_subs\*(C'\fR \- stable as of perl 5.22, available via stable 0.031
133 .Sp
134 Lexical subroutines were actually added in 5.18, and their design did not
135 change, but significant bugs makes them unsafe to use before 5.22.
136 .IP \(bu 4
137 \&\f(CW\*(C`postderef\*(C'\fR \- stable as of perl 5.20, available via stable 0.031
138 .IP \(bu 4
139 \&\f(CW\*(C`const_attr\*(C'\fR \- stable as of perl 5.22, available via stable 0.032
140 .IP \(bu 4
141 \&\f(CW\*(C`for_list\*(C'\fR \- stable as of perl 5.36, available via stable 0.032
142 .SH "SEE ALSO"
143 .IX Header "SEE ALSO"
144 perlexperiment contains more information about experimental features.
145 .SH AUTHOR
146 .IX Header "AUTHOR"
147 Leon Timmermans <[email protected]>
148 .SH "COPYRIGHT AND LICENSE"
149 .IX Header "COPYRIGHT AND LICENSE"
150 This software is copyright (c) 2013 by Leon Timmermans.
151 .PP
152 This is free software; you can redistribute it and/or modify it under
153 the same terms as the Perl 5 programming language system itself.