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