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