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