Debian Codegraph @

upstream/mageia-cauldron/man3pm/stable.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "stable 3pm"
61 .TH stable 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 stable \- Experimental features made easy, once we know they\*(Aqre stable
68 .SH VERSION
69 .IX Header "VERSION"
70 version 0.035
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 2
74 \& use stable \*(Aqlexical_subs\*(Aq, \*(Aqbitwise\*(Aq;
75 \& my sub is_odd($value) { $value & 1 }
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 The experimental pragma makes it easy to turn on experiments while turning
80 off associated warnings. You should read about it, if you don\*(Aqt already know
81 what it does.
82 .PP
83 Seeing \f(CW\*(C`use experimental\*(C'\fR in code might be scary. In fact, it probably should
84 be! Code that uses experimental features might break in the future if the perl
85 development team decides that the experiment needs to be altered. When
86 experiments become stable, because the developers decide they\*(Aqre a success, the
87 warnings associated with them go away. When that happens, they can generally
88 be turned on with \f(CW\*(C`use feature\*(C'\fR.
89 .PP
90 This is great, if you are using a version of perl where the feature you want is
91 already stable. If you\*(Aqre using an older perl, though, it might be the case
92 that you want to use an experimental feature that still warns, even though
93 there\*(Aqs no risk in using it, because subsequent versions of perl have that
94 feature unchanged and now stable.
95 .PP
96 Here\*(Aqs an example: The \f(CW\*(C`postderef\*(C'\fR feature was added in perl 5.20.0. In perl
97 5.24.0, it was marked stable. Using it would no longer trigger a warning. The
98 behavior of the feature didn\*(Aqt change between 5.20.0 and 5.24.0. That means
99 that it\*(Aqs perfectly safe to use the feature on 5.20 or 5.22, even though
100 there\*(Aqs a warning.
101 .PP
102 In that case, you could very justifiably add \f(CW\*(C`use experimental \*(Aqpostderef\*(Aq\*(C'\fR
103 but the casual reader may still be worried at seeing that. The \f(CW\*(C`stable\*(C'\fR
104 pragma exists to turn on experimental features only when it\*(Aqs known that
105 their behavior in the running perl is their stable behavior.
106 .PP
107 If you try to use an experimental feature that isn\*(Aqt stable or available on
108 the running version of perl, an exception will be thrown. You should also take
109 care that you\*(Aqve required the version of \f(CW\*(C`stable\*(C'\fR that you need!
110 .PP
111 If it\*(Aqs not immediately obvious why, here\*(Aqs a bit of explanation:
112 .IP \(bu 4
113 \&\f(CW\*(C`stable\*(C'\fR comes with perl, starting with perl v5.38.
114 .IP \(bu 4
115 Imagine that v5.38 adds a feature called "florps". It will stop being
116 experimental in v5.42.
117 .IP \(bu 4
118 The version of \f(CW\*(C`stable\*(C'\fR that comes with perl v5.38 can\*(Aqt know that the
119 \&\fIflorps\fR experiment will succeed, so you can\*(Aqt \f(CW\*(C`use stable \*(Aqflorps\*(Aq\*(C'\fR on the
120 version of stable ships with v5.38, because it can\*(Aqt see the future!
121 .IP \(bu 4
122 You\*(Aqll need to write \f(CW\*(C`use stable 1.234 \*(Aqflorps\*(Aq\*(C'\fR to say that you need version
123 1.234 of stable, which is when \fIflorps\fR became known to stable.
124 .PP
125 Sure, it\*(Aqs a little weird, but it\*(Aqs worth it! The documentation of this pragma
126 will tell you what version of \f(CW\*(C`stable\*(C'\fR you need to require in order to use
127 various features. See below.
128 .PP
129 At present there are only a few "stable" features:
130 .IP \(bu 4
131 \&\f(CW\*(C`bitwise\*(C'\fR \- stable as of perl 5.22, available via stable 0.031
132 .IP \(bu 4
133 \&\f(CW\*(C`isa\*(C'\fR \- stable as of perl 5.32, available via stable 0.031
134 .IP \(bu 4
135 \&\f(CW\*(C`lexical_subs\*(C'\fR \- stable as of perl 5.22, available via stable 0.031
136 .Sp
137 Lexical subroutines were actually added in 5.18, and their design did not
138 change, but significant bugs makes them unsafe to use before 5.22.
139 .IP \(bu 4
140 \&\f(CW\*(C`postderef\*(C'\fR \- stable as of perl 5.20, available via stable 0.031
141 .IP \(bu 4
142 \&\f(CW\*(C`const_attr\*(C'\fR \- stable as of perl 5.22, available via stable 0.032
143 .IP \(bu 4
144 \&\f(CW\*(C`for_list\*(C'\fR \- stable as of perl 5.36, available via stable 0.032
145 .SH "SEE ALSO"
146 .IX Header "SEE ALSO"
147 perlexperiment contains more information about experimental features.
148 .SH AUTHOR
149 .IX Header "AUTHOR"
150 Leon Timmermans <[email protected]>
151 .SH "COPYRIGHT AND LICENSE"
152 .IX Header "COPYRIGHT AND LICENSE"
153 This software is copyright (c) 2013 by Leon Timmermans.
154 .PP
155 This is free software; you can redistribute it and/or modify it under
156 the same terms as the Perl 5 programming language system itself.