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