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