This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #72724] explicit return doesn’t work with lvalue subs
[perl5.git] / lib / feature.pm
CommitLineData
0d863452
RH
1package feature;
2
8891dd8d 3our $VERSION = '1.21';
0d863452
RH
4
5# (feature name) => (internal name, used in %^H)
6my %feature = (
1863b879
RGS
7 switch => 'feature_switch',
8 say => "feature_say",
9 state => "feature_state",
10 unicode_strings => "feature_unicode",
bc9b29db
RH
11);
12
1863b879
RGS
13# This gets set (for now) in $^H as well as in %^H,
14# for runtime speed of the uc/lc/ucfirst/lcfirst functions.
b0f41c9d 15# See HINT_UNI_8_BIT in perl.h.
1863b879
RGS
16our $hint_uni8bit = 0x00000800;
17
13a7998c
RGS
18# NB. the latest bundle must be loaded by the -E switch (see toke.c)
19
bc9b29db 20my %feature_bundle = (
82cfb3a2 21 "5.10" => [qw(switch say state)],
1863b879 22 "5.11" => [qw(switch say state unicode_strings)],
b7569deb 23 "5.12" => [qw(switch say state unicode_strings)],
e836a73b 24 "5.13" => [qw(switch say state unicode_strings)],
11ca38a1 25 "5.14" => [qw(switch say state unicode_strings)],
8891dd8d 26 "5.15" => [qw(switch say state unicode_strings)],
0d863452 27);
d052521a 28
82cfb3a2
S
29# special case
30$feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
7dfde25d 31
0d863452 32# TODO:
1c321dc6 33# - think about versioned features (use feature switch => 2)
0d863452
RH
34
35=head1 NAME
36
e1b711da 37feature - Perl pragma to enable new features
0d863452
RH
38
39=head1 SYNOPSIS
40
bc9b29db 41 use feature qw(switch say);
0d863452 42 given ($foo) {
bc9b29db
RH
43 when (1) { say "\$foo == 1" }
44 when ([2,3]) { say "\$foo == 2 || \$foo == 3" }
45 when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
46 when ($_ > 100) { say "\$foo > 100" }
47 default { say "None of the above" }
0d863452
RH
48 }
49
ec488c7f
RGS
50 use feature ':5.10'; # loads all features available in perl 5.10
51
0d863452
RH
52=head1 DESCRIPTION
53
54It is usually impossible to add new syntax to Perl without breaking
55some existing programs. This pragma provides a way to minimize that
1863b879
RGS
56risk. New syntactic constructs, or new semantic meanings to older
57constructs, can be enabled by C<use feature 'foo'>, and will be parsed
58only when the appropriate feature pragma is in scope.
0d863452 59
9eb27be9
RGS
60=head2 Lexical effect
61
62Like other pragmas (C<use strict>, for example), features have a lexical
5e36ed56 63effect. C<use feature qw(foo)> will only make the feature "foo" available
9eb27be9
RGS
64from that point to the end of the enclosing block.
65
66 {
67 use feature 'say';
68 say "say is available here";
69 }
70 print "But not here.\n";
71
5e36ed56
RGS
72=head2 C<no feature>
73
74Features can also be turned off by using C<no feature "foo">. This too
75has lexical effect.
76
77 use feature 'say';
78 say "say is available here";
79 {
80 no feature 'say';
81 print "But not here.\n";
82 }
83 say "Yet it is here.";
84
85C<no feature> with no features specified will turn off all features.
86
0d863452
RH
87=head2 The 'switch' feature
88
89C<use feature 'switch'> tells the compiler to enable the Perl 6
9eb27be9 90given/when construct.
0d863452
RH
91
92See L<perlsyn/"Switch statements"> for details.
93
0d863452
RH
94=head2 The 'say' feature
95
96C<use feature 'say'> tells the compiler to enable the Perl 6
9eb27be9 97C<say> function.
0d863452
RH
98
99See L<perlfunc/say> for details.
100
712d05cf
RGS
101=head2 the 'state' feature
102
103C<use feature 'state'> tells the compiler to enable C<state>
9eb27be9 104variables.
712d05cf 105
e60bcc8b
RGS
106See L<perlsub/"Persistent Private Variables"> for details.
107
1863b879
RGS
108=head2 the 'unicode_strings' feature
109
20db7501
KW
110C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
111in all string operations executed within its scope (unless they are also
112within the scope of either C<use locale> or C<use bytes>). The same applies
113to all regular expressions compiled within the scope, even if executed outside
114it.
115
116C<no feature 'unicode_strings'> tells the compiler to use the traditional
117Perl semantics wherein the native character set semantics is used unless it is
118clear to Perl that Unicode is desired. This can lead to some surprises
119when the behavior suddenly changes. (See
120L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
121potentially using Unicode in your program, the
122C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
123
124This subpragma is available starting with Perl 5.11.3, but was not fully
125implemented until 5.13.8.
1863b879 126
bc9b29db
RH
127=head1 FEATURE BUNDLES
128
129It's possible to load a whole slew of features in one go, using
130a I<feature bundle>. The name of a feature bundle is prefixed with
131a colon, to distinguish it from an actual feature. At present, the
82cfb3a2
S
132only feature bundle is C<use feature ":5.10"> which is equivalent
133to C<use feature qw(switch say state)>.
8fd870d9 134
82cfb3a2
S
135Specifying sub-versions such as the C<0> in C<5.10.0> in feature bundles has
136no effect: feature bundles are guaranteed to be the same for all sub-versions.
bc9b29db 137
7dfde25d
RGS
138=head1 IMPLICIT LOADING
139
140There are two ways to load the C<feature> pragma implicitly :
141
142=over 4
143
144=item *
145
146By using the C<-E> switch on the command-line instead of C<-e>. It enables
147all available features in the main compilation unit (that is, the one-liner.)
148
149=item *
150
151By requiring explicitly a minimal Perl version number for your program, with
152the C<use VERSION> construct, and when the version is higher than or equal to
8d115822 1535.10.0. That is,
7dfde25d 154
8d115822 155 use 5.10.0;
7dfde25d
RGS
156
157will do an implicit
158
82cfb3a2 159 use feature ':5.10';
7dfde25d 160
82cfb3a2
S
161and so on. Note how the trailing sub-version is automatically stripped from the
162version.
7dfde25d 163
8d115822
RB
164But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
165
166 use 5.010;
167
168with the same effect.
169
7dfde25d
RGS
170=back
171
0d863452
RH
172=cut
173
174sub import {
0d863452
RH
175 my $class = shift;
176 if (@_ == 0) {
0d863452
RH
177 croak("No features specified");
178 }
179 while (@_) {
180 my $name = shift(@_);
89c3975a
RGS
181 if (substr($name, 0, 1) eq ":") {
182 my $v = substr($name, 1);
7be54ea7 183 if (!exists $feature_bundle{$v}) {
82cfb3a2
S
184 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
185 if (!exists $feature_bundle{$v}) {
186 unknown_feature_bundle(substr($name, 1));
187 }
bc9b29db 188 }
7be54ea7 189 unshift @_, @{$feature_bundle{$v}};
bc9b29db
RH
190 next;
191 }
0d863452 192 if (!exists $feature{$name}) {
b42943c4 193 unknown_feature($name);
0d863452
RH
194 }
195 $^H{$feature{$name}} = 1;
1863b879 196 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
0d863452
RH
197 }
198}
199
200sub unimport {
201 my $class = shift;
202
203 # A bare C<no feature> should disable *all* features
bc9b29db
RH
204 if (!@_) {
205 delete @^H{ values(%feature) };
1863b879 206 $^H &= ~ $hint_uni8bit;
bc9b29db
RH
207 return;
208 }
209
210 while (@_) {
211 my $name = shift;
89c3975a
RGS
212 if (substr($name, 0, 1) eq ":") {
213 my $v = substr($name, 1);
7be54ea7 214 if (!exists $feature_bundle{$v}) {
82cfb3a2
S
215 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
216 if (!exists $feature_bundle{$v}) {
217 unknown_feature_bundle(substr($name, 1));
218 }
bc9b29db 219 }
7be54ea7 220 unshift @_, @{$feature_bundle{$v}};
bc9b29db
RH
221 next;
222 }
0d863452 223 if (!exists($feature{$name})) {
b42943c4 224 unknown_feature($name);
0d863452
RH
225 }
226 else {
227 delete $^H{$feature{$name}};
1863b879 228 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
0d863452
RH
229 }
230 }
0d863452
RH
231}
232
b42943c4
RGS
233sub unknown_feature {
234 my $feature = shift;
235 croak(sprintf('Feature "%s" is not supported by Perl %vd',
236 $feature, $^V));
237}
238
239sub unknown_feature_bundle {
240 my $feature = shift;
241 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
242 $feature, $^V));
243}
244
245sub croak {
246 require Carp;
247 Carp::croak(@_);
248}
249
0d863452 2501;