1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "stable 3pm"
.TH stable 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
stable \- Experimental features made easy, once we know they're stable
.SH VERSION
.IX Header "VERSION"
version 0.031
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& use stable \*(Aqlexical_subs\*(Aq, \*(Aqbitwise\*(Aq;
\& my sub is_odd($value) { $value & 1 }
.Ve
.SH DESCRIPTION
.IX Header "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.
.PP
Seeing \f(CW\*(C`use experimental\*(C'\fR 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 \f(CW\*(C`use feature\*(C'\fR.
.PP
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.
.PP
Here's an example: The \f(CW\*(C`postderef\*(C'\fR 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.
.PP
In that case, you could very justifiably add \f(CW\*(C`use experimental \*(Aqpostderef\*(Aq\*(C'\fR
but the casual reader may still be worried at seeing that. The \f(CW\*(C`stable\*(C'\fR
pragma exists to turn on experimental features only when it's known that
their behavior in the running perl is their stable behavior.
.PP
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 \f(CW\*(C`stable\*(C'\fR that you need!
.PP
If it's not immediately obvious why, here's a bit of explanation:
.IP \(bu 4
\&\f(CW\*(C`stable\*(C'\fR comes with perl, starting with perl v5.38.
.IP \(bu 4
Imagine that v5.38 adds a feature called "florps". It will stop being
experimental in v5.42.
.IP \(bu 4
The version of \f(CW\*(C`stable\*(C'\fR that comes with perl v5.38 can't know that the
\&\fIflorps\fR experiment will succeed, so you can't \f(CW\*(C`use stable \*(Aqflorps\*(Aq\*(C'\fR on the
version of stable ships with v5.38, because it can't see the future!
.IP \(bu 4
You'll need to write \f(CW\*(C`use stable 1.234 \*(Aqflorps\*(Aq\*(C'\fR to say that you need version
1.234 of stable, which is when \fIflorps\fR became known to stable.
.PP
Sure, it's a little weird, but it's worth it! The documentation of this pragma
will tell you what version of \f(CW\*(C`stable\*(C'\fR you need to require in order to use
various features. See below.
.PP
At present there are only a few "stable" features:
.IP \(bu 4
\&\f(CW\*(C`bitwise\*(C'\fR \- stable as of perl 5.22, available via stable 0.031
.IP \(bu 4
\&\f(CW\*(C`isa\*(C'\fR \- stable as of perl 5.32, available via stable 0.031
.IP \(bu 4
\&\f(CW\*(C`lexical_subs\*(C'\fR \- stable as of perl 5.22, available via stable 0.031
.Sp
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.
.IP \(bu 4
\&\f(CW\*(C`postderef\*(C'\fR \- stable as of perl 5.20, available via stable 0.031
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perlexperiment contains more information about experimental features.
.SH AUTHOR
.IX Header "AUTHOR"
Leon Timmermans <leont@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2013 by Leon Timmermans.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
|
