Commit | Line | Data |
---|---|---|
69bcf1d3 FC |
1 | #!/usr/bin/perl |
2 | # | |
3 | # Regenerate (overwriting only if changed): | |
4 | # | |
5 | # lib/feature.pm | |
f2c01b15 | 6 | # feature.h |
69bcf1d3 | 7 | # |
3489ea76 | 8 | # from information hardcoded into this script and from two #defines |
d73d634c | 9 | # in perl.h. |
69bcf1d3 FC |
10 | # |
11 | # This script is normally invoked from regen.pl. | |
12 | ||
13 | BEGIN { | |
3d7c117d | 14 | require './regen/regen_lib.pl'; |
69bcf1d3 FC |
15 | push @INC, './lib'; |
16 | } | |
17 | use strict ; | |
18 | ||
c452a42f FC |
19 | |
20 | ########################################################################### | |
21 | # Hand-editable data | |
22 | ||
c6b36e45 | 23 | # (feature name) => (internal name, used in %^H and macro names) |
69bcf1d3 | 24 | my %feature = ( |
67bdaa9e FC |
25 | say => 'say', |
26 | state => 'state', | |
27 | switch => 'switch', | |
cec892e7 | 28 | bitwise => 'bitwise', |
67bdaa9e FC |
29 | evalbytes => 'evalbytes', |
30 | current_sub => '__SUB__', | |
baabe3fb | 31 | refaliasing => 'refaliasing', |
158becca | 32 | postderef_qq => 'postderef_qq', |
67bdaa9e | 33 | unicode_eval => 'unieval', |
82d83da3 | 34 | declared_refs => 'myref', |
67bdaa9e | 35 | unicode_strings => 'unicode', |
2a4315f8 | 36 | fc => 'fc', |
30d9c59b | 37 | signatures => 'signatures', |
69bcf1d3 FC |
38 | ); |
39 | ||
40e4d872 FC |
40 | # NOTE: If a feature is ever enabled in a non-contiguous range of Perl |
41 | # versions, any code below that uses %BundleRanges will have to | |
42 | # be changed to account. | |
43 | ||
52fc5c56 | 44 | # 5.odd implies the next 5.even, but an explicit 5.even can override it. |
69bcf1d3 | 45 | my %feature_bundle = ( |
39ec54a5 | 46 | all => [ keys %feature ], |
c22e17d0 DIM |
47 | default => [qw()], |
48 | "5.9.5" => [qw(say state switch)], | |
49 | "5.10" => [qw(say state switch)], | |
50 | "5.11" => [qw(say state switch unicode_strings)], | |
51 | "5.13" => [qw(say state switch unicode_strings)], | |
69bcf1d3 | 52 | "5.15" => [qw(say state switch unicode_strings unicode_eval |
2a4315f8 | 53 | evalbytes current_sub fc)], |
d6402ebe RS |
54 | "5.17" => [qw(say state switch unicode_strings unicode_eval |
55 | evalbytes current_sub fc)], | |
d09258e7 RS |
56 | "5.19" => [qw(say state switch unicode_strings unicode_eval |
57 | evalbytes current_sub fc)], | |
b530a4ea RS |
58 | "5.21" => [qw(say state switch unicode_strings unicode_eval |
59 | evalbytes current_sub fc)], | |
6031f0d2 | 60 | "5.23" => [qw(say state switch unicode_strings unicode_eval |
1c2511e0 | 61 | evalbytes current_sub fc postderef_qq)], |
2c5484a6 RS |
62 | "5.25" => [qw(say state switch unicode_strings unicode_eval |
63 | evalbytes current_sub fc postderef_qq)], | |
c35a148e | 64 | "5.27" => [qw(say state switch unicode_strings unicode_eval |
401d2aaa | 65 | evalbytes current_sub fc postderef_qq bitwise)], |
d361a1e6 S |
66 | "5.29" => [qw(say state switch unicode_strings unicode_eval |
67 | evalbytes current_sub fc postderef_qq bitwise)], | |
b85fe491 S |
68 | "5.31" => [qw(say state switch unicode_strings unicode_eval |
69 | evalbytes current_sub fc postderef_qq bitwise)], | |
69bcf1d3 FC |
70 | ); |
71 | ||
db629560 | 72 | my @noops = qw( postderef lexical_subs ); |
c22e17d0 | 73 | my @removed = qw( array_base ); |
db629560 | 74 | |
c452a42f | 75 | |
69bcf1d3 | 76 | ########################################################################### |
c452a42f | 77 | # More data generated from the above |
69bcf1d3 | 78 | |
9f601cf3 TC |
79 | if (keys %feature > 32) { |
80 | die "cop_features only has room for 32 features"; | |
81 | } | |
82 | ||
83 | my %feature_bits; | |
84 | my $mask = 1; | |
85 | for my $feature (sort keys %feature) { | |
86 | $feature_bits{$feature} = $mask; | |
87 | $mask <<= 1; | |
88 | } | |
89 | ||
52fc5c56 FC |
90 | for (keys %feature_bundle) { |
91 | next unless /^5\.(\d*[13579])\z/; | |
92 | $feature_bundle{"5.".($1+1)} ||= $feature_bundle{$_}; | |
93 | } | |
94 | ||
f2c01b15 FC |
95 | my %UniqueBundles; # "say state switch" => 5.10 |
96 | my %Aliases; # 5.12 => 5.11 | |
97 | for( sort keys %feature_bundle ) { | |
98 | my $value = join(' ', sort @{$feature_bundle{$_}}); | |
99 | if (exists $UniqueBundles{$value}) { | |
100 | $Aliases{$_} = $UniqueBundles{$value}; | |
101 | } | |
102 | else { | |
103 | $UniqueBundles{$value} = $_; | |
104 | } | |
105 | } | |
40e4d872 FC |
106 | # start end |
107 | my %BundleRanges; # say => ['5.10', '5.15'] # unique bundles for values | |
108 | for my $bund ( | |
109 | sort { $a eq 'default' ? -1 : $b eq 'default' ? 1 : $a cmp $b } | |
110 | values %UniqueBundles | |
111 | ) { | |
03222170 | 112 | next if $bund =~ /[^\d.]/ and $bund ne 'default'; |
40e4d872 FC |
113 | for (@{$feature_bundle{$bund}}) { |
114 | if (@{$BundleRanges{$_} ||= []} == 2) { | |
115 | $BundleRanges{$_}[1] = $bund | |
116 | } | |
117 | else { | |
118 | push @{$BundleRanges{$_}}, $bund; | |
119 | } | |
120 | } | |
121 | } | |
69bcf1d3 | 122 | |
47222a2d | 123 | my $HintShift; |
ada44f8c | 124 | my $HintMask; |
3489ea76 | 125 | my $Uni8Bit; |
47222a2d | 126 | |
1ae6ead9 | 127 | open "perl.h", "<", "perl.h" or die "$0 cannot open perl.h: $!"; |
3489ea76 FC |
128 | while (readline "perl.h") { |
129 | next unless /#\s*define\s+(HINT_FEATURE_MASK|HINT_UNI_8_BIT)/; | |
130 | my $is_u8b = $1 =~ 8; | |
131 | /(0x[A-Fa-f0-9]+)/ or die "No hex number in:\n\n$_\n "; | |
132 | if ($is_u8b) { | |
133 | $Uni8Bit = $1; | |
134 | } | |
135 | else { | |
ada44f8c | 136 | my $hex = $HintMask = $1; |
47222a2d FC |
137 | my $bits = sprintf "%b", oct $1; |
138 | $bits =~ /^0*1+(0*)\z/ | |
139 | or die "Non-contiguous bits in $bits (binary for $hex):\n\n$_\n "; | |
140 | $HintShift = length $1; | |
141 | my $bits_needed = | |
142 | length sprintf "%b", scalar keys %UniqueBundles; | |
143 | $bits =~ /1{$bits_needed}/ | |
144 | or die "Not enough bits (need $bits_needed)" | |
5d826eae | 145 | . " in $bits (binary for $hex):\n\n$_\n "; |
47222a2d | 146 | } |
3489ea76 | 147 | if ($Uni8Bit && $HintMask) { last } |
47222a2d | 148 | } |
3489ea76 FC |
149 | die "No HINT_FEATURE_MASK defined in perl.h" unless $HintMask; |
150 | die "No HINT_UNI_8_BIT defined in perl.h" unless $Uni8Bit; | |
151 | ||
47222a2d FC |
152 | close "perl.h"; |
153 | ||
ada44f8c FC |
154 | my @HintedBundles = |
155 | ('default', grep !/[^\d.]/, sort values %UniqueBundles); | |
156 | ||
47222a2d | 157 | |
f2c01b15 | 158 | ########################################################################### |
c452a42f | 159 | # Open files to be generated |
f2c01b15 FC |
160 | |
161 | my ($pm, $h) = map { | |
69bcf1d3 | 162 | open_new($_, '>', { by => 'regen/feature.pl' }); |
f2c01b15 | 163 | } 'lib/feature.pm', 'feature.h'; |
69bcf1d3 FC |
164 | |
165 | ||
c452a42f FC |
166 | ########################################################################### |
167 | # Generate lib/feature.pm | |
168 | ||
69bcf1d3 FC |
169 | while (<DATA>) { |
170 | last if /^FEATURES$/ ; | |
171 | print $pm $_ ; | |
172 | } | |
173 | ||
174 | sub longest { | |
175 | my $long; | |
176 | for(@_) { | |
177 | if (!defined $long or length $long < length) { | |
178 | $long = $_; | |
179 | } | |
180 | } | |
181 | $long; | |
182 | } | |
183 | ||
0bb01b05 | 184 | print $pm "our %feature = (\n"; |
69bcf1d3 | 185 | my $width = length longest keys %feature; |
ebd25686 | 186 | for(sort { length $a <=> length $b || $a cmp $b } keys %feature) { |
67bdaa9e FC |
187 | print $pm " $_" . " "x($width-length) |
188 | . " => 'feature_$feature{$_}',\n"; | |
69bcf1d3 FC |
189 | } |
190 | print $pm ");\n\n"; | |
191 | ||
9f601cf3 TC |
192 | print $pm "\nmy %feature_bits = (\n"; |
193 | for (sort keys %feature_bits) { | |
194 | printf $pm " %-*s => %#06x,\n", $width, $_, $feature_bits{$_}; | |
195 | } | |
196 | print $pm ");\n\n"; | |
197 | ||
69bcf1d3 | 198 | print $pm "our %feature_bundle = (\n"; |
9f601cf3 | 199 | my $bund_width = length longest values %UniqueBundles; |
88da30d7 FC |
200 | for( sort { $UniqueBundles{$a} cmp $UniqueBundles{$b} } |
201 | keys %UniqueBundles ) { | |
202 | my $bund = $UniqueBundles{$_}; | |
9f601cf3 | 203 | print $pm qq' "$bund"' . " "x($bund_width-length $bund) |
88da30d7 | 204 | . qq' => [qw($_)],\n'; |
69bcf1d3 FC |
205 | } |
206 | print $pm ");\n\n"; | |
207 | ||
88da30d7 FC |
208 | for (sort keys %Aliases) { |
209 | print $pm | |
210 | qq'\$feature_bundle{"$_"} = \$feature_bundle{"$Aliases{$_}"};\n'; | |
211 | }; | |
69bcf1d3 | 212 | |
db629560 FC |
213 | print $pm "my \%noops = (\n"; |
214 | print $pm " $_ => 1,\n", for @noops; | |
215 | print $pm ");\n"; | |
216 | ||
c22e17d0 DIM |
217 | print $pm "my \%removed = (\n"; |
218 | print $pm " $_ => 1,\n", for @removed; | |
219 | print $pm ");\n"; | |
220 | ||
ada44f8c FC |
221 | print $pm <<EOPM; |
222 | ||
0bb01b05 FC |
223 | our \$hint_shift = $HintShift; |
224 | our \$hint_mask = $HintMask; | |
225 | our \@hint_bundles = qw( @HintedBundles ); | |
3489ea76 FC |
226 | |
227 | # This gets set (for now) in \$^H as well as in %^H, | |
228 | # for runtime speed of the uc/lc/ucfirst/lcfirst functions. | |
229 | # See HINT_UNI_8_BIT in perl.h. | |
230 | our \$hint_uni8bit = $Uni8Bit; | |
ada44f8c FC |
231 | EOPM |
232 | ||
69bcf1d3 FC |
233 | |
234 | while (<DATA>) { | |
2b3fe414 FC |
235 | last if /^PODTURES$/ ; |
236 | print $pm $_ ; | |
237 | } | |
238 | ||
239 | select +(select($pm), $~ = 'PODTURES')[0]; | |
240 | format PODTURES = | |
241 | ^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~ | |
242 | $::bundle, $::feature | |
243 | . | |
244 | ||
245 | for ('default', sort grep /\.\d[02468]/, keys %feature_bundle) { | |
246 | $::bundle = ":$_"; | |
247 | $::feature = join ' ', @{$feature_bundle{$_}}; | |
248 | write $pm; | |
249 | print $pm "\n"; | |
250 | } | |
251 | ||
252 | while (<DATA>) { | |
69bcf1d3 FC |
253 | print $pm $_ ; |
254 | } | |
255 | ||
256 | read_only_bottom_close_and_rename($pm); | |
257 | ||
c452a42f FC |
258 | |
259 | ########################################################################### | |
260 | # Generate feature.h | |
261 | ||
f2c01b15 FC |
262 | print $h <<EOH; |
263 | ||
3dd7db29 JK |
264 | #ifndef PERL_FEATURE_H_ |
265 | #define PERL_FEATURE_H_ | |
266 | ||
f2c01b15 FC |
267 | #if defined(PERL_CORE) || defined (PERL_EXT) |
268 | ||
269 | #define HINT_FEATURE_SHIFT $HintShift | |
270 | ||
f2c01b15 FC |
271 | EOH |
272 | ||
9f601cf3 TC |
273 | for (sort keys %feature_bits) { |
274 | printf $h "#define FEATURE_%s_BIT%*s %#06x\n", uc($feature{$_}), | |
275 | $width-length($feature{$_}), "", $feature_bits{$_}; | |
276 | } | |
277 | print $h "\n"; | |
278 | ||
f2c01b15 | 279 | my $count; |
016d11cb FC |
280 | for (@HintedBundles) { |
281 | (my $key = uc) =~ y/.//d; | |
282 | print $h "#define FEATURE_BUNDLE_$key ", $count++, "\n"; | |
f2c01b15 FC |
283 | } |
284 | ||
7d058bc9 | 285 | print $h <<'EOH'; |
2b9e0ab7 | 286 | #define FEATURE_BUNDLE_CUSTOM (HINT_FEATURE_MASK >> HINT_FEATURE_SHIFT) |
f2c01b15 | 287 | |
7d058bc9 | 288 | #define CURRENT_HINTS \ |
d1fd0100 | 289 | (PL_curcop == &PL_compiling ? PL_hints : PL_curcop->cop_hints) |
035b6821 FC |
290 | #define CURRENT_FEATURE_BUNDLE \ |
291 | ((CURRENT_HINTS & HINT_FEATURE_MASK) >> HINT_FEATURE_SHIFT) | |
d1fd0100 | 292 | |
9f601cf3 TC |
293 | #define FEATURE_IS_ENABLED_MASK(mask) \ |
294 | ((CURRENT_HINTS & HINT_LOCALIZE_HH) \ | |
295 | ? (PL_curcop->cop_features & (mask)) : FALSE) | |
296 | ||
7d058bc9 | 297 | /* The longest string we pass in. */ |
03222170 FC |
298 | EOH |
299 | ||
1b6e8741 FC |
300 | my $longest_internal_feature_name = longest values %feature; |
301 | print $h <<EOL; | |
302 | #define MAX_FEATURE_LEN (sizeof("$longest_internal_feature_name")-1) | |
303 | ||
304 | EOL | |
305 | ||
03222170 | 306 | for ( |
ebd25686 | 307 | sort { length $a <=> length $b || $a cmp $b } keys %feature |
03222170 FC |
308 | ) { |
309 | my($first,$last) = | |
310 | map { (my $__ = uc) =~ y/.//d; $__ } @{$BundleRanges{$_}}; | |
3fff3427 | 311 | my $name = $feature{$_}; |
03222170 | 312 | my $NAME = uc $name; |
f298f061 | 313 | if ($last && $first eq 'DEFAULT') { # '>= DEFAULT' warns |
beda0318 | 314 | print $h <<EOI; |
23fa16fc | 315 | #define FEATURE_${NAME}_IS_ENABLED \\ |
beda0318 FC |
316 | ( \\ |
317 | CURRENT_FEATURE_BUNDLE <= FEATURE_BUNDLE_$last \\ | |
318 | || (CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_CUSTOM && \\ | |
23fa16fc | 319 | FEATURE_IS_ENABLED_MASK(FEATURE_${NAME}_BIT)) \\ |
beda0318 FC |
320 | ) |
321 | ||
322 | EOI | |
323 | } | |
324 | elsif ($last) { | |
03222170 | 325 | print $h <<EOH3; |
23fa16fc | 326 | #define FEATURE_${NAME}_IS_ENABLED \\ |
03222170 FC |
327 | ( \\ |
328 | (CURRENT_FEATURE_BUNDLE >= FEATURE_BUNDLE_$first && \\ | |
329 | CURRENT_FEATURE_BUNDLE <= FEATURE_BUNDLE_$last) \\ | |
330 | || (CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_CUSTOM && \\ | |
23fa16fc | 331 | FEATURE_IS_ENABLED_MASK(FEATURE_${NAME}_BIT)) \\ |
03222170 FC |
332 | ) |
333 | ||
334 | EOH3 | |
335 | } | |
ebd25686 | 336 | elsif ($first) { |
03222170 | 337 | print $h <<EOH4; |
23fa16fc | 338 | #define FEATURE_${NAME}_IS_ENABLED \\ |
03222170 FC |
339 | ( \\ |
340 | CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_$first \\ | |
341 | || (CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_CUSTOM && \\ | |
23fa16fc | 342 | FEATURE_IS_ENABLED_MASK(FEATURE_${NAME}_BIT)) \\ |
03222170 FC |
343 | ) |
344 | ||
345 | EOH4 | |
346 | } | |
ebd25686 FC |
347 | else { |
348 | print $h <<EOH5; | |
23fa16fc | 349 | #define FEATURE_${NAME}_IS_ENABLED \\ |
ebd25686 FC |
350 | ( \\ |
351 | CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_CUSTOM && \\ | |
23fa16fc | 352 | FEATURE_IS_ENABLED_MASK(FEATURE_${NAME}_BIT) \\ |
ebd25686 FC |
353 | ) |
354 | ||
355 | EOH5 | |
356 | } | |
03222170 FC |
357 | } |
358 | ||
359 | print $h <<EOH; | |
360 | ||
9f601cf3 TC |
361 | #define SAVEFEATUREBITS() SAVEI32(PL_compiling.cop_features) |
362 | ||
363 | #define CLEARFEATUREBITS() (PL_compiling.cop_features = 0) | |
364 | ||
365 | #define STOREFEATUREBITSHH(hh) \\ | |
366 | (hv_stores((hh), "feature/bits", newSVuv(PL_compiling.cop_features))) | |
367 | ||
368 | #define FETCHFEATUREBITSHH(hh) \\ | |
369 | STMT_START { \\ | |
370 | SV **fbsv = hv_fetchs((hh), "feature/bits", FALSE); \\ | |
371 | PL_compiling.cop_features = fbsv ? SvUV(*fbsv) : 0; \\ | |
372 | } STMT_END | |
373 | ||
f2c01b15 | 374 | #endif /* PERL_CORE or PERL_EXT */ |
4160ddbd FC |
375 | |
376 | #ifdef PERL_IN_OP_C | |
377 | PERL_STATIC_INLINE void | |
378 | S_enable_feature_bundle(pTHX_ SV *ver) | |
379 | { | |
380 | SV *comp_ver = sv_newmortal(); | |
381 | PL_hints = (PL_hints &~ HINT_FEATURE_MASK) | |
382 | | ( | |
f2c01b15 FC |
383 | EOH |
384 | ||
4160ddbd FC |
385 | for (reverse @HintedBundles[1..$#HintedBundles]) { # skip default |
386 | my $numver = $_; | |
387 | if ($numver eq '5.10') { $numver = '5.009005' } # special case | |
388 | else { $numver =~ s/\./.0/ } # 5.11 => 5.011 | |
389 | (my $macrover = $_) =~ y/.//d; | |
390 | print $h <<" EOK"; | |
391 | (sv_setnv(comp_ver, $numver), | |
392 | vcmp(ver, upg_version(comp_ver, FALSE)) >= 0) | |
393 | ? FEATURE_BUNDLE_$macrover : | |
394 | EOK | |
395 | } | |
396 | ||
397 | print $h <<EOJ; | |
398 | FEATURE_BUNDLE_DEFAULT | |
399 | ) << HINT_FEATURE_SHIFT; | |
6389c777 FC |
400 | /* special case */ |
401 | assert(PL_curcop == &PL_compiling); | |
402 | if (FEATURE_UNICODE_IS_ENABLED) PL_hints |= HINT_UNI_8_BIT; | |
403 | else PL_hints &= ~HINT_UNI_8_BIT; | |
4160ddbd FC |
404 | } |
405 | #endif /* PERL_IN_OP_C */ | |
3dd7db29 JK |
406 | |
407 | #endif /* PERL_FEATURE_H_ */ | |
4160ddbd FC |
408 | EOJ |
409 | ||
f2c01b15 FC |
410 | read_only_bottom_close_and_rename($h); |
411 | ||
c452a42f FC |
412 | |
413 | ########################################################################### | |
414 | # Template for feature.pm | |
415 | ||
69bcf1d3 FC |
416 | __END__ |
417 | package feature; | |
418 | ||
9f601cf3 | 419 | our $VERSION = '1.56'; |
69bcf1d3 FC |
420 | |
421 | FEATURES | |
422 | ||
69bcf1d3 FC |
423 | # TODO: |
424 | # - think about versioned features (use feature switch => 2) | |
425 | ||
426 | =head1 NAME | |
427 | ||
428 | feature - Perl pragma to enable new features | |
429 | ||
430 | =head1 SYNOPSIS | |
431 | ||
432 | use feature qw(say switch); | |
433 | given ($foo) { | |
434 | when (1) { say "\$foo == 1" } | |
435 | when ([2,3]) { say "\$foo == 2 || \$foo == 3" } | |
436 | when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" } | |
437 | when ($_ > 100) { say "\$foo > 100" } | |
438 | default { say "None of the above" } | |
439 | } | |
440 | ||
441 | use feature ':5.10'; # loads all features available in perl 5.10 | |
442 | ||
443 | use v5.10; # implicitly loads :5.10 feature bundle | |
444 | ||
445 | =head1 DESCRIPTION | |
446 | ||
447 | It is usually impossible to add new syntax to Perl without breaking | |
448 | some existing programs. This pragma provides a way to minimize that | |
449 | risk. New syntactic constructs, or new semantic meanings to older | |
450 | constructs, can be enabled by C<use feature 'foo'>, and will be parsed | |
451 | only when the appropriate feature pragma is in scope. (Nevertheless, the | |
452 | C<CORE::> prefix provides access to all Perl keywords, regardless of this | |
453 | pragma.) | |
454 | ||
455 | =head2 Lexical effect | |
456 | ||
457 | Like other pragmas (C<use strict>, for example), features have a lexical | |
301381dc | 458 | effect. C<use feature qw(foo)> will only make the feature "foo" available |
69bcf1d3 FC |
459 | from that point to the end of the enclosing block. |
460 | ||
461 | { | |
462 | use feature 'say'; | |
463 | say "say is available here"; | |
464 | } | |
465 | print "But not here.\n"; | |
466 | ||
467 | =head2 C<no feature> | |
468 | ||
469 | Features can also be turned off by using C<no feature "foo">. This too | |
470 | has lexical effect. | |
471 | ||
472 | use feature 'say'; | |
473 | say "say is available here"; | |
474 | { | |
475 | no feature 'say'; | |
476 | print "But not here.\n"; | |
477 | } | |
478 | say "Yet it is here."; | |
479 | ||
39ec54a5 RS |
480 | C<no feature> with no features specified will reset to the default group. To |
481 | disable I<all> features (an unusual request!) use C<no feature ':all'>. | |
69bcf1d3 FC |
482 | |
483 | =head1 AVAILABLE FEATURES | |
484 | ||
485 | =head2 The 'say' feature | |
486 | ||
487 | C<use feature 'say'> tells the compiler to enable the Perl 6 style | |
488 | C<say> function. | |
489 | ||
490 | See L<perlfunc/say> for details. | |
491 | ||
492 | This feature is available starting with Perl 5.10. | |
493 | ||
494 | =head2 The 'state' feature | |
495 | ||
496 | C<use feature 'state'> tells the compiler to enable C<state> | |
497 | variables. | |
498 | ||
499 | See L<perlsub/"Persistent Private Variables"> for details. | |
500 | ||
501 | This feature is available starting with Perl 5.10. | |
502 | ||
503 | =head2 The 'switch' feature | |
504 | ||
7caca87c DB |
505 | B<WARNING>: Because the L<smartmatch operator|perlop/"Smartmatch Operator"> is |
506 | experimental, Perl will warn when you use this feature, unless you have | |
507 | explicitly disabled the warning: | |
508 | ||
509 | no warnings "experimental::smartmatch"; | |
510 | ||
7896dde7 | 511 | C<use feature 'switch'> tells the compiler to enable the Perl 6 |
69bcf1d3 FC |
512 | given/when construct. |
513 | ||
48238296 | 514 | See L<perlsyn/"Switch Statements"> for details. |
69bcf1d3 FC |
515 | |
516 | This feature is available starting with Perl 5.10. | |
517 | ||
518 | =head2 The 'unicode_strings' feature | |
519 | ||
850b7ec9 | 520 | C<use feature 'unicode_strings'> tells the compiler to use Unicode rules |
69bcf1d3 FC |
521 | in all string operations executed within its scope (unless they are also |
522 | within the scope of either C<use locale> or C<use bytes>). The same applies | |
523 | to all regular expressions compiled within the scope, even if executed outside | |
2269d15c KW |
524 | it. It does not change the internal representation of strings, but only how |
525 | they are interpreted. | |
69bcf1d3 FC |
526 | |
527 | C<no feature 'unicode_strings'> tells the compiler to use the traditional | |
850b7ec9 | 528 | Perl rules wherein the native character set rules is used unless it is |
69bcf1d3 FC |
529 | clear to Perl that Unicode is desired. This can lead to some surprises |
530 | when the behavior suddenly changes. (See | |
531 | L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are | |
532 | potentially using Unicode in your program, the | |
533 | C<use feature 'unicode_strings'> subpragma is B<strongly> recommended. | |
534 | ||
2e2b2571 | 535 | This feature is available starting with Perl 5.12; was almost fully |
d6c970c7 | 536 | implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>; |
20ae58f7 AC |
537 | was extended further in Perl 5.26 to cover L<the range |
538 | operator|perlop/Range Operators>; and was extended again in Perl 5.28 to | |
539 | cover L<special-cased whitespace splitting|perlfunc/split>. | |
69bcf1d3 FC |
540 | |
541 | =head2 The 'unicode_eval' and 'evalbytes' features | |
542 | ||
9891e9b7 KW |
543 | Together, these two features are intended to replace the legacy string |
544 | C<eval> function, which behaves problematically in some instances. They are | |
545 | available starting with Perl 5.16, and are enabled by default by a | |
546 | S<C<use 5.16>> or higher declaration. | |
547 | ||
548 | C<unicode_eval> changes the behavior of plain string C<eval> to work more | |
549 | consistently, especially in the Unicode world. Certain (mis)behaviors | |
550 | couldn't be changed without breaking some things that had come to rely on | |
551 | them, so the feature can be enabled and disabled. Details are at | |
552 | L<perlfunc/Under the "unicode_eval" feature>. | |
553 | ||
554 | C<evalbytes> is like string C<eval>, but operating on a byte stream that is | |
555 | not UTF-8 encoded. Details are at L<perlfunc/evalbytes EXPR>. Without a | |
556 | S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in | |
557 | the current scope, you can still access it by instead writing | |
558 | C<CORE::evalbytes>. | |
69bcf1d3 FC |
559 | |
560 | =head2 The 'current_sub' feature | |
561 | ||
562 | This provides the C<__SUB__> token that returns a reference to the current | |
563 | subroutine or C<undef> outside of a subroutine. | |
564 | ||
565 | This feature is available starting with Perl 5.16. | |
566 | ||
567 | =head2 The 'array_base' feature | |
568 | ||
c22e17d0 DIM |
569 | This feature supported the legacy C<$[> variable. See L<perlvar/$[>. |
570 | It was on by default but disabled under C<use v5.16> (see | |
571 | L</IMPLICIT LOADING>, below) and unavailable since perl 5.30. | |
69bcf1d3 FC |
572 | |
573 | This feature is available under this name starting with Perl 5.16. In | |
574 | previous versions, it was simply on all the time, and this pragma knew | |
575 | nothing about it. | |
576 | ||
2a4315f8 BF |
577 | =head2 The 'fc' feature |
578 | ||
579 | C<use feature 'fc'> tells the compiler to enable the C<fc> function, | |
580 | which implements Unicode casefolding. | |
581 | ||
582 | See L<perlfunc/fc> for details. | |
583 | ||
584 | This feature is available from Perl 5.16 onwards. | |
585 | ||
ca40957e FC |
586 | =head2 The 'lexical_subs' feature |
587 | ||
8f7d85af FC |
588 | In Perl versions prior to 5.26, this feature enabled |
589 | declaration of subroutines via C<my sub foo>, C<state sub foo> | |
590 | and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details. | |
ca40957e | 591 | |
8f7d85af FC |
592 | This feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24, |
593 | it was classed as experimental, and Perl emitted a warning for its | |
594 | usage, except when explicitly disabled: | |
ca40957e | 595 | |
8f7d85af | 596 | no warnings "experimental::lexical_subs"; |
ca40957e | 597 | |
8f7d85af FC |
598 | As of Perl 5.26, use of this feature no longer triggers a warning, though |
599 | the C<experimental::lexical_subs> warning category still exists (for | |
600 | compatibility with code that disables it). In addition, this syntax is | |
601 | not only no longer experimental, but it is enabled for all Perl code, | |
602 | regardless of what feature declarations are in scope. | |
ca40957e | 603 | |
f86d720e RS |
604 | =head2 The 'postderef' and 'postderef_qq' features |
605 | ||
1c2511e0 AC |
606 | The 'postderef_qq' feature extends the applicability of L<postfix |
607 | dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array | |
608 | and scalar dereference are available in double-quotish interpolations. For | |
609 | example, it makes the following two statements equivalent: | |
f86d720e | 610 | |
1c2511e0 AC |
611 | my $s = "[@{ $h->{a} }]"; |
612 | my $s = "[$h->{a}->@*]"; | |
f86d720e | 613 | |
1c2511e0 AC |
614 | This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it |
615 | was classed as experimental, and Perl emitted a warning for its | |
2ad792cd AC |
616 | usage, except when explicitly disabled: |
617 | ||
618 | no warnings "experimental::postderef"; | |
619 | ||
1c2511e0 | 620 | As of Perl 5.24, use of this feature no longer triggers a warning, though |
2ad792cd AC |
621 | the C<experimental::postderef> warning category still exists (for |
622 | compatibility with code that disables it). | |
f86d720e | 623 | |
1c2511e0 AC |
624 | The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable |
625 | postfix dereference syntax outside double-quotish interpolations. In those | |
626 | versions, using it triggered the C<experimental::postderef> warning in the | |
627 | same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is | |
628 | not only no longer experimental, but it is enabled for all Perl code, | |
629 | regardless of what feature declarations are in scope. | |
630 | ||
30d9c59b Z |
631 | =head2 The 'signatures' feature |
632 | ||
633 | B<WARNING>: This feature is still experimental and the implementation may | |
634 | change in future versions of Perl. For this reason, Perl will | |
635 | warn when you use the feature, unless you have explicitly disabled the | |
636 | warning: | |
637 | ||
638 | no warnings "experimental::signatures"; | |
639 | ||
640 | This enables unpacking of subroutine arguments into lexical variables | |
641 | by syntax such as | |
642 | ||
643 | sub foo ($left, $right) { | |
644 | return $left + $right; | |
645 | } | |
646 | ||
647 | See L<perlsub/Signatures> for details. | |
648 | ||
649 | This feature is available from Perl 5.20 onwards. | |
650 | ||
baabe3fb | 651 | =head2 The 'refaliasing' feature |
82848c10 FC |
652 | |
653 | B<WARNING>: This feature is still experimental and the implementation may | |
654 | change in future versions of Perl. For this reason, Perl will | |
655 | warn when you use the feature, unless you have explicitly disabled the | |
656 | warning: | |
657 | ||
baabe3fb | 658 | no warnings "experimental::refaliasing"; |
82848c10 FC |
659 | |
660 | This enables aliasing via assignment to references: | |
661 | ||
662 | \$a = \$b; # $a and $b now point to the same scalar | |
663 | \@a = \@b; # to the same array | |
664 | \%a = \%b; | |
665 | \&a = \&b; | |
666 | foreach \%hash (@array_of_hash_refs) { | |
667 | ... | |
668 | } | |
669 | ||
670 | See L<perlref/Assigning to References> for details. | |
671 | ||
672 | This feature is available from Perl 5.22 onwards. | |
673 | ||
70ea8edf FC |
674 | =head2 The 'bitwise' feature |
675 | ||
70ea8edf FC |
676 | This makes the four standard bitwise operators (C<& | ^ ~>) treat their |
677 | operands consistently as numbers, and introduces four new dotted operators | |
678 | (C<&. |. ^. ~.>) that treat their operands consistently as strings. The | |
679 | same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>). | |
680 | ||
681 | See L<perlop/Bitwise String Operators> for details. | |
682 | ||
193789ac FC |
683 | This feature is available from Perl 5.22 onwards. Starting in Perl 5.28, |
684 | C<use v5.28> will enable the feature. Before 5.28, it was still | |
685 | experimental and would emit a warning in the "experimental::bitwise" | |
686 | category. | |
70ea8edf | 687 | |
5c703779 FC |
688 | =head2 The 'declared_refs' feature |
689 | ||
690 | B<WARNING>: This feature is still experimental and the implementation may | |
691 | change in future versions of Perl. For this reason, Perl will | |
692 | warn when you use the feature, unless you have explicitly disabled the | |
693 | warning: | |
694 | ||
695 | no warnings "experimental::declared_refs"; | |
696 | ||
697 | This allows a reference to a variable to be declared with C<my>, C<state>, | |
698 | our C<our>, or localized with C<local>. It is intended mainly for use in | |
699 | conjunction with the "refaliasing" feature. See L<perlref/Declaring a | |
700 | Reference to a Variable> for examples. | |
701 | ||
702 | This feature is available from Perl 5.26 onwards. | |
703 | ||
69bcf1d3 FC |
704 | =head1 FEATURE BUNDLES |
705 | ||
706 | It's possible to load multiple features together, using | |
707 | a I<feature bundle>. The name of a feature bundle is prefixed with | |
708 | a colon, to distinguish it from an actual feature. | |
709 | ||
710 | use feature ":5.10"; | |
711 | ||
712 | The following feature bundles are available: | |
713 | ||
714 | bundle features included | |
715 | --------- ----------------- | |
2b3fe414 | 716 | PODTURES |
69bcf1d3 FC |
717 | The C<:default> bundle represents the feature set that is enabled before |
718 | any C<use feature> or C<no feature> declaration. | |
719 | ||
720 | Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has | |
721 | no effect. Feature bundles are guaranteed to be the same for all sub-versions. | |
722 | ||
723 | use feature ":5.14.0"; # same as ":5.14" | |
724 | use feature ":5.14.1"; # same as ":5.14" | |
725 | ||
726 | =head1 IMPLICIT LOADING | |
727 | ||
728 | Instead of loading feature bundles by name, it is easier to let Perl do | |
729 | implicit loading of a feature bundle for you. | |
730 | ||
731 | There are two ways to load the C<feature> pragma implicitly: | |
732 | ||
733 | =over 4 | |
734 | ||
735 | =item * | |
736 | ||
737 | By using the C<-E> switch on the Perl command-line instead of C<-e>. | |
738 | That will enable the feature bundle for that version of Perl in the | |
739 | main compilation unit (that is, the one-liner that follows C<-E>). | |
740 | ||
741 | =item * | |
742 | ||
743 | By explicitly requiring a minimum Perl version number for your program, with | |
744 | the C<use VERSION> construct. That is, | |
745 | ||
746 | use v5.10.0; | |
747 | ||
748 | will do an implicit | |
749 | ||
39ec54a5 | 750 | no feature ':all'; |
69bcf1d3 FC |
751 | use feature ':5.10'; |
752 | ||
753 | and so on. Note how the trailing sub-version | |
754 | is automatically stripped from the | |
755 | version. | |
756 | ||
757 | But to avoid portability warnings (see L<perlfunc/use>), you may prefer: | |
758 | ||
759 | use 5.010; | |
760 | ||
761 | with the same effect. | |
762 | ||
763 | If the required version is older than Perl 5.10, the ":default" feature | |
764 | bundle is automatically loaded instead. | |
765 | ||
affe54fa AC |
766 | Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version) |
767 | also does the equivalent of C<use strict>; see L<perlfunc/use> for details. | |
768 | ||
69bcf1d3 FC |
769 | =back |
770 | ||
771 | =cut | |
772 | ||
773 | sub import { | |
22055af9 | 774 | shift; |
36143a0c NC |
775 | |
776 | if (!@_) { | |
69bcf1d3 FC |
777 | croak("No features specified"); |
778 | } | |
36143a0c | 779 | |
d3757264 | 780 | __common(1, @_); |
69bcf1d3 FC |
781 | } |
782 | ||
783 | sub unimport { | |
22055af9 | 784 | shift; |
69bcf1d3 | 785 | |
39ec54a5 | 786 | # A bare C<no feature> should reset to the default bundle |
69bcf1d3 | 787 | if (!@_) { |
39ec54a5 RS |
788 | $^H &= ~($hint_uni8bit|$hint_mask); |
789 | return; | |
69bcf1d3 FC |
790 | } |
791 | ||
d3757264 NC |
792 | __common(0, @_); |
793 | } | |
794 | ||
795 | ||
796 | sub __common { | |
797 | my $import = shift; | |
0c8d5017 NC |
798 | my $bundle_number = $^H & $hint_mask; |
799 | my $features = $bundle_number != $hint_mask | |
9f601cf3 TC |
800 | && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]}; |
801 | my $bits = ${^FEATURE_BITS}; | |
0c8d5017 | 802 | if ($features) { |
da5b5421 | 803 | # Features are enabled implicitly via bundle hints. |
d9ee6ccb NC |
804 | # Delete any keys that may be left over from last time. |
805 | delete @^H{ values(%feature) }; | |
9f601cf3 | 806 | $bits = 0; |
d9ee6ccb NC |
807 | $^H |= $hint_mask; |
808 | for (@$features) { | |
809 | $^H{$feature{$_}} = 1; | |
9f601cf3 | 810 | $bits |= $feature_bits{$_}; |
d9ee6ccb NC |
811 | $^H |= $hint_uni8bit if $_ eq 'unicode_strings'; |
812 | } | |
da5b5421 | 813 | } |
69bcf1d3 FC |
814 | while (@_) { |
815 | my $name = shift; | |
816 | if (substr($name, 0, 1) eq ":") { | |
817 | my $v = substr($name, 1); | |
818 | if (!exists $feature_bundle{$v}) { | |
819 | $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/; | |
820 | if (!exists $feature_bundle{$v}) { | |
821 | unknown_feature_bundle(substr($name, 1)); | |
822 | } | |
823 | } | |
824 | unshift @_, @{$feature_bundle{$v}}; | |
825 | next; | |
826 | } | |
36143a0c | 827 | if (!exists $feature{$name}) { |
db629560 FC |
828 | if (exists $noops{$name}) { |
829 | next; | |
830 | } | |
c22e17d0 DIM |
831 | if (!$import && exists $removed{$name}) { |
832 | next; | |
833 | } | |
69bcf1d3 | 834 | unknown_feature($name); |
69bcf1d3 | 835 | } |
d3757264 NC |
836 | if ($import) { |
837 | $^H{$feature{$name}} = 1; | |
9f601cf3 | 838 | $bits |= $feature_bits{$name}; |
d3757264 NC |
839 | $^H |= $hint_uni8bit if $name eq 'unicode_strings'; |
840 | } else { | |
69bcf1d3 | 841 | delete $^H{$feature{$name}}; |
9f601cf3 | 842 | $bits &= ~$feature_bits{$name}; |
69bcf1d3 FC |
843 | $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings'; |
844 | } | |
845 | } | |
9f601cf3 | 846 | ${^FEATURE_BITS} = $bits; |
69bcf1d3 FC |
847 | } |
848 | ||
849 | sub unknown_feature { | |
850 | my $feature = shift; | |
851 | croak(sprintf('Feature "%s" is not supported by Perl %vd', | |
852 | $feature, $^V)); | |
853 | } | |
854 | ||
855 | sub unknown_feature_bundle { | |
856 | my $feature = shift; | |
857 | croak(sprintf('Feature bundle "%s" is not supported by Perl %vd', | |
858 | $feature, $^V)); | |
859 | } | |
860 | ||
861 | sub croak { | |
862 | require Carp; | |
863 | Carp::croak(@_); | |
864 | } | |
865 | ||
866 | 1; |