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