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