This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Increase $feature::VERSION to 1.31
[perl5.git] / lib / feature.pm
CommitLineData
69bcf1d3
FC
1# -*- buffer-read-only: t -*-
2# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
3# This file is built by regen/feature.pl.
4# Any changes made here will be lost!
5
0d863452
RH
6package feature;
7
23d16d50 8our $VERSION = '1.31';
0d863452 9
0bb01b05 10our %feature = (
2a4315f8 11 fc => 'feature_fc',
47e9d84a
EB
12 say => 'feature_say',
13 state => 'feature_state',
1863b879 14 switch => 'feature_switch',
7d789282 15 evalbytes => 'feature_evalbytes',
3fff3427 16 array_base => 'feature_arybase',
84ed0108 17 current_sub => 'feature___SUB__',
ebd25686 18 lexical_subs => 'feature_lexsubs',
cda6b701 19 unicode_eval => 'feature_unieval',
47e9d84a 20 unicode_strings => 'feature_unicode',
bc9b29db
RH
21);
22
0d2bd2aa 23our %feature_bundle = (
69bcf1d3
FC
24 "5.10" => [qw(array_base say state switch)],
25 "5.11" => [qw(array_base say state switch unicode_strings)],
2a4315f8 26 "5.15" => [qw(current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
ebd25686 27 "all" => [qw(array_base current_sub evalbytes fc lexical_subs say state switch unicode_eval unicode_strings)],
69bcf1d3 28 "default" => [qw(array_base)],
0d863452 29);
d052521a 30
88da30d7
FC
31$feature_bundle{"5.12"} = $feature_bundle{"5.11"};
32$feature_bundle{"5.13"} = $feature_bundle{"5.11"};
33$feature_bundle{"5.14"} = $feature_bundle{"5.11"};
34$feature_bundle{"5.16"} = $feature_bundle{"5.15"};
d6402ebe 35$feature_bundle{"5.17"} = $feature_bundle{"5.15"};
52fc5c56 36$feature_bundle{"5.18"} = $feature_bundle{"5.15"};
88da30d7 37$feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
ebd25686
FC
38my %experimental = (
39 lexical_subs => 1,
40);
69bcf1d3 41
0bb01b05
FC
42our $hint_shift = 26;
43our $hint_mask = 0x1c000000;
44our @hint_bundles = qw( default 5.10 5.11 5.15 );
ada44f8c 45
69bcf1d3
FC
46# This gets set (for now) in $^H as well as in %^H,
47# for runtime speed of the uc/lc/ucfirst/lcfirst functions.
48# See HINT_UNI_8_BIT in perl.h.
49our $hint_uni8bit = 0x00000800;
7dfde25d 50
0d863452 51# TODO:
1c321dc6 52# - think about versioned features (use feature switch => 2)
0d863452
RH
53
54=head1 NAME
55
e1b711da 56feature - Perl pragma to enable new features
0d863452
RH
57
58=head1 SYNOPSIS
59
47e9d84a 60 use feature qw(say switch);
0d863452 61 given ($foo) {
0b25e784
DG
62 when (1) { say "\$foo == 1" }
63 when ([2,3]) { say "\$foo == 2 || \$foo == 3" }
64 when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
65 when ($_ > 100) { say "\$foo > 100" }
66 default { say "None of the above" }
0d863452
RH
67 }
68
ec488c7f
RGS
69 use feature ':5.10'; # loads all features available in perl 5.10
70
0b25e784
DG
71 use v5.10; # implicitly loads :5.10 feature bundle
72
0d863452
RH
73=head1 DESCRIPTION
74
75It is usually impossible to add new syntax to Perl without breaking
b22bbcf0 76some existing programs. This pragma provides a way to minimize that
1863b879
RGS
77risk. New syntactic constructs, or new semantic meanings to older
78constructs, can be enabled by C<use feature 'foo'>, and will be parsed
b22bbcf0 79only when the appropriate feature pragma is in scope. (Nevertheless, the
4a904372
FC
80C<CORE::> prefix provides access to all Perl keywords, regardless of this
81pragma.)
0d863452 82
9eb27be9
RGS
83=head2 Lexical effect
84
85Like other pragmas (C<use strict>, for example), features have a lexical
301381dc 86effect. C<use feature qw(foo)> will only make the feature "foo" available
9eb27be9
RGS
87from that point to the end of the enclosing block.
88
89 {
90 use feature 'say';
91 say "say is available here";
92 }
93 print "But not here.\n";
94
5e36ed56
RGS
95=head2 C<no feature>
96
b22bbcf0 97Features can also be turned off by using C<no feature "foo">. This too
5e36ed56
RGS
98has lexical effect.
99
100 use feature 'say';
101 say "say is available here";
102 {
103 no feature 'say';
104 print "But not here.\n";
105 }
106 say "Yet it is here.";
107
39ec54a5
RS
108C<no feature> with no features specified will reset to the default group. To
109disable I<all> features (an unusual request!) use C<no feature ':all'>.
5e36ed56 110
0b25e784
DG
111=head1 AVAILABLE FEATURES
112
0d863452
RH
113=head2 The 'say' feature
114
0b25e784 115C<use feature 'say'> tells the compiler to enable the Perl 6 style
9eb27be9 116C<say> function.
0d863452
RH
117
118See L<perlfunc/say> for details.
119
0b25e784
DG
120This feature is available starting with Perl 5.10.
121
122=head2 The 'state' feature
712d05cf
RGS
123
124C<use feature 'state'> tells the compiler to enable C<state>
9eb27be9 125variables.
712d05cf 126
e60bcc8b
RGS
127See L<perlsub/"Persistent Private Variables"> for details.
128
0b25e784
DG
129This feature is available starting with Perl 5.10.
130
47e9d84a
EB
131=head2 The 'switch' feature
132
133C<use feature 'switch'> tells the compiler to enable the Perl 6
134given/when construct.
135
48238296 136See L<perlsyn/"Switch Statements"> for details.
47e9d84a 137
0b25e784
DG
138This feature is available starting with Perl 5.10.
139
140=head2 The 'unicode_strings' feature
1863b879 141
20db7501
KW
142C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
143in all string operations executed within its scope (unless they are also
144within the scope of either C<use locale> or C<use bytes>). The same applies
145to all regular expressions compiled within the scope, even if executed outside
2269d15c
KW
146it. It does not change the internal representation of strings, but only how
147they are interpreted.
20db7501
KW
148
149C<no feature 'unicode_strings'> tells the compiler to use the traditional
150Perl semantics wherein the native character set semantics is used unless it is
151clear to Perl that Unicode is desired. This can lead to some surprises
152when the behavior suddenly changes. (See
153L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
154potentially using Unicode in your program, the
155C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
156
2e2b2571
KW
157This feature is available starting with Perl 5.12; was almost fully
158implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>.
1863b879 159
0b25e784 160=head2 The 'unicode_eval' and 'evalbytes' features
7289c5e6
FC
161
162Under the C<unicode_eval> feature, Perl's C<eval> function, when passed a
163string, will evaluate it as a string of characters, ignoring any
164C<use utf8> declarations. C<use utf8> exists to declare the encoding of
165the script, which only makes sense for a stream of bytes, not a string of
166characters. Source filters are forbidden, as they also really only make
167sense on strings of bytes. Any attempt to activate a source filter will
168result in an error.
169
170The C<evalbytes> feature enables the C<evalbytes> keyword, which evaluates
171the argument passed to it as a string of bytes. It dies if the string
172contains any characters outside the 8-bit range. Source filters work
173within C<evalbytes>: they apply to the contents of the string being
174evaluated.
175
176Together, these two features are intended to replace the historical C<eval>
177function, which has (at least) two bugs in it, that cannot easily be fixed
178without breaking existing programs:
179
180=over
181
182=item *
183
184C<eval> behaves differently depending on the internal encoding of the
185string, sometimes treating its argument as a string of bytes, and sometimes
186as a string of characters.
187
188=item *
189
190Source filters activated within C<eval> leak out into whichever I<file>
191scope is currently being compiled. To give an example with the CPAN module
192L<Semi::Semicolons>:
193
194 BEGIN { eval "use Semi::Semicolons; # not filtered here " }
195 # filtered here!
196
197C<evalbytes> fixes that to work the way one would expect:
198
199 use feature "evalbytes";
200 BEGIN { evalbytes "use Semi::Semicolons; # filtered " }
201 # not filtered
202
203=back
204
205These two features are available starting with Perl 5.16.
206
84ed0108
FC
207=head2 The 'current_sub' feature
208
209This provides the C<__SUB__> token that returns a reference to the current
210subroutine or C<undef> outside of a subroutine.
211
212This feature is available starting with Perl 5.16.
213
01868d00
FC
214=head2 The 'array_base' feature
215
216This feature supports the legacy C<$[> variable. See L<perlvar/$[> and
217L<arybase>. It is on by default but disabled under C<use v5.16> (see
218L</IMPLICIT LOADING>, below).
219
220This feature is available under this name starting with Perl 5.16. In
221previous versions, it was simply on all the time, and this pragma knew
222nothing about it.
223
2a4315f8
BF
224=head2 The 'fc' feature
225
226C<use feature 'fc'> tells the compiler to enable the C<fc> function,
227which implements Unicode casefolding.
228
229See L<perlfunc/fc> for details.
230
231This feature is available from Perl 5.16 onwards.
232
ca40957e
FC
233=head2 The 'lexical_subs' feature
234
235B<WARNING>: This feature is still experimental and the implementation may
236change in future versions of Perl. For this reason, F<feature.pm> will
237warn when you enable the feature, unless you have explicitly disabled the
238warning:
239
f1d34ca8 240 no warnings "experimental::lexical_subs";
ca40957e
FC
241
242This enables declaration of subroutines via C<my sub foo>, C<state sub foo>
243and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details.
244
245This feature is available from Perl 5.18 onwards.
246
bc9b29db
RH
247=head1 FEATURE BUNDLES
248
0b25e784 249It's possible to load multiple features together, using
b22bbcf0 250a I<feature bundle>. The name of a feature bundle is prefixed with
0b25e784
DG
251a colon, to distinguish it from an actual feature.
252
253 use feature ":5.10";
254
255The following feature bundles are available:
256
257 bundle features included
258 --------- -----------------
01868d00 259 :default array_base
0b25e784 260
01868d00 261 :5.10 say state switch array_base
0b25e784 262
01868d00 263 :5.12 say state switch unicode_strings array_base
0b25e784 264
01868d00 265 :5.14 say state switch unicode_strings array_base
0b25e784
DG
266
267 :5.16 say state switch unicode_strings
2a4315f8 268 unicode_eval evalbytes current_sub fc
0b25e784 269
52fc5c56
FC
270 :5.18 say state switch unicode_strings
271 unicode_eval evalbytes current_sub fc
272
01868d00
FC
273The C<:default> bundle represents the feature set that is enabled before
274any C<use feature> or C<no feature> declaration.
a3a91442
JV
275
276Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
b22bbcf0 277no effect. Feature bundles are guaranteed to be the same for all sub-versions.
bc9b29db 278
0b25e784
DG
279 use feature ":5.14.0"; # same as ":5.14"
280 use feature ":5.14.1"; # same as ":5.14"
a3a91442 281
7dfde25d
RGS
282=head1 IMPLICIT LOADING
283
0b25e784
DG
284Instead of loading feature bundles by name, it is easier to let Perl do
285implicit loading of a feature bundle for you.
286
287There are two ways to load the C<feature> pragma implicitly:
7dfde25d
RGS
288
289=over 4
290
291=item *
292
0b25e784
DG
293By using the C<-E> switch on the Perl command-line instead of C<-e>.
294That will enable the feature bundle for that version of Perl in the
295main compilation unit (that is, the one-liner that follows C<-E>).
7dfde25d
RGS
296
297=item *
298
0b25e784 299By explicitly requiring a minimum Perl version number for your program, with
b22bbcf0 300the C<use VERSION> construct. That is,
7dfde25d 301
0b25e784 302 use v5.10.0;
7dfde25d
RGS
303
304will do an implicit
305
39ec54a5 306 no feature ':all';
82cfb3a2 307 use feature ':5.10';
7dfde25d 308
b22bbcf0
FC
309and so on. Note how the trailing sub-version
310is automatically stripped from the
82cfb3a2 311version.
7dfde25d 312
8d115822
RB
313But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
314
315 use 5.010;
316
317with the same effect.
318
0b25e784 319If the required version is older than Perl 5.10, the ":default" feature
01868d00 320bundle is automatically loaded instead.
70397346 321
7dfde25d
RGS
322=back
323
0d863452
RH
324=cut
325
326sub import {
0d863452 327 my $class = shift;
36143a0c
NC
328
329 if (!@_) {
0b25e784 330 croak("No features specified");
0d863452 331 }
36143a0c 332
d3757264 333 __common(1, @_);
0d863452
RH
334}
335
336sub unimport {
337 my $class = shift;
338
39ec54a5 339 # A bare C<no feature> should reset to the default bundle
bc9b29db 340 if (!@_) {
39ec54a5
RS
341 $^H &= ~($hint_uni8bit|$hint_mask);
342 return;
bc9b29db
RH
343 }
344
d3757264
NC
345 __common(0, @_);
346}
347
348
349sub __common {
350 my $import = shift;
0c8d5017
NC
351 my $bundle_number = $^H & $hint_mask;
352 my $features = $bundle_number != $hint_mask
353 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
354 if ($features) {
da5b5421 355 # Features are enabled implicitly via bundle hints.
d9ee6ccb
NC
356 # Delete any keys that may be left over from last time.
357 delete @^H{ values(%feature) };
358 $^H |= $hint_mask;
359 for (@$features) {
360 $^H{$feature{$_}} = 1;
361 $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
362 }
da5b5421 363 }
bc9b29db 364 while (@_) {
0b25e784
DG
365 my $name = shift;
366 if (substr($name, 0, 1) eq ":") {
367 my $v = substr($name, 1);
368 if (!exists $feature_bundle{$v}) {
369 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
370 if (!exists $feature_bundle{$v}) {
371 unknown_feature_bundle(substr($name, 1));
372 }
373 }
374 unshift @_, @{$feature_bundle{$v}};
375 next;
376 }
36143a0c 377 if (!exists $feature{$name}) {
0b25e784
DG
378 unknown_feature($name);
379 }
d3757264
NC
380 if ($import) {
381 $^H{$feature{$name}} = 1;
382 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
ebd25686
FC
383 if ($experimental{$name}) {
384 require warnings;
f1d34ca8 385 warnings::warnif("experimental::$name",
ebd25686
FC
386 "The $name feature is experimental");
387 }
d3757264 388 } else {
0b25e784 389 delete $^H{$feature{$name}};
1863b879 390 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
0b25e784 391 }
0d863452 392 }
0d863452
RH
393}
394
b42943c4
RGS
395sub unknown_feature {
396 my $feature = shift;
397 croak(sprintf('Feature "%s" is not supported by Perl %vd',
0b25e784 398 $feature, $^V));
b42943c4
RGS
399}
400
401sub unknown_feature_bundle {
402 my $feature = shift;
403 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
0b25e784 404 $feature, $^V));
b42943c4
RGS
405}
406
407sub croak {
408 require Carp;
409 Carp::croak(@_);
410}
411
0d863452 4121;
69bcf1d3
FC
413
414# ex: set ro: