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