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
6package feature;
7
8our $VERSION = '1.64';
9
10our %feature = (
11    fc                   => 'feature_fc',
12    isa                  => 'feature_isa',
13    say                  => 'feature_say',
14    try                  => 'feature_try',
15    state                => 'feature_state',
16    switch               => 'feature_switch',
17    bitwise              => 'feature_bitwise',
18    indirect             => 'feature_indirect',
19    evalbytes            => 'feature_evalbytes',
20    signatures           => 'feature_signatures',
21    current_sub          => 'feature___SUB__',
22    refaliasing          => 'feature_refaliasing',
23    postderef_qq         => 'feature_postderef_qq',
24    unicode_eval         => 'feature_unieval',
25    declared_refs        => 'feature_myref',
26    unicode_strings      => 'feature_unicode',
27    multidimensional     => 'feature_multidimensional',
28    bareword_filehandles => 'feature_bareword_filehandles',
29);
30
31our %feature_bundle = (
32    "5.10"    => [qw(bareword_filehandles indirect multidimensional say state switch)],
33    "5.11"    => [qw(bareword_filehandles indirect multidimensional say state switch unicode_strings)],
34    "5.15"    => [qw(bareword_filehandles current_sub evalbytes fc indirect multidimensional say state switch unicode_eval unicode_strings)],
35    "5.23"    => [qw(bareword_filehandles current_sub evalbytes fc indirect multidimensional postderef_qq say state switch unicode_eval unicode_strings)],
36    "5.27"    => [qw(bareword_filehandles bitwise current_sub evalbytes fc indirect multidimensional postderef_qq say state switch unicode_eval unicode_strings)],
37    "all"     => [qw(bareword_filehandles bitwise current_sub declared_refs evalbytes fc indirect isa multidimensional postderef_qq refaliasing say signatures state switch try unicode_eval unicode_strings)],
38    "default" => [qw(bareword_filehandles indirect multidimensional)],
39);
40
41$feature_bundle{"5.12"} = $feature_bundle{"5.11"};
42$feature_bundle{"5.13"} = $feature_bundle{"5.11"};
43$feature_bundle{"5.14"} = $feature_bundle{"5.11"};
44$feature_bundle{"5.16"} = $feature_bundle{"5.15"};
45$feature_bundle{"5.17"} = $feature_bundle{"5.15"};
46$feature_bundle{"5.18"} = $feature_bundle{"5.15"};
47$feature_bundle{"5.19"} = $feature_bundle{"5.15"};
48$feature_bundle{"5.20"} = $feature_bundle{"5.15"};
49$feature_bundle{"5.21"} = $feature_bundle{"5.15"};
50$feature_bundle{"5.22"} = $feature_bundle{"5.15"};
51$feature_bundle{"5.24"} = $feature_bundle{"5.23"};
52$feature_bundle{"5.25"} = $feature_bundle{"5.23"};
53$feature_bundle{"5.26"} = $feature_bundle{"5.23"};
54$feature_bundle{"5.28"} = $feature_bundle{"5.27"};
55$feature_bundle{"5.29"} = $feature_bundle{"5.27"};
56$feature_bundle{"5.30"} = $feature_bundle{"5.27"};
57$feature_bundle{"5.31"} = $feature_bundle{"5.27"};
58$feature_bundle{"5.32"} = $feature_bundle{"5.27"};
59$feature_bundle{"5.33"} = $feature_bundle{"5.27"};
60$feature_bundle{"5.34"} = $feature_bundle{"5.27"};
61$feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
62my %noops = (
63    postderef => 1,
64    lexical_subs => 1,
65);
66my %removed = (
67    array_base => 1,
68);
69
70our $hint_shift   = 26;
71our $hint_mask    = 0x3c000000;
72our @hint_bundles = qw( default 5.10 5.11 5.15 5.23 5.27 );
73
74# This gets set (for now) in $^H as well as in %^H,
75# for runtime speed of the uc/lc/ucfirst/lcfirst functions.
76# See HINT_UNI_8_BIT in perl.h.
77our $hint_uni8bit = 0x00000800;
78
79# TODO:
80# - think about versioned features (use feature switch => 2)
81
82=head1 NAME
83
84feature - Perl pragma to enable new features
85
86=head1 SYNOPSIS
87
88    use feature qw(fc say);
89
90    # Without the "use feature" above, this code would not be able to find
91    # the built-ins "say" or "fc":
92    say "The case-folded version of $x is: " . fc $x;
93
94
95    # set features to match the :5.10 bundle, which may turn off or on
96    # multiple features (see below)
97    use feature ':5.10';
98
99
100    # implicitly loads :5.10 feature bundle
101    use v5.10;
102
103=head1 DESCRIPTION
104
105It is usually impossible to add new syntax to Perl without breaking
106some existing programs.  This pragma provides a way to minimize that
107risk. New syntactic constructs, or new semantic meanings to older
108constructs, can be enabled by C<use feature 'foo'>, and will be parsed
109only when the appropriate feature pragma is in scope.  (Nevertheless, the
110C<CORE::> prefix provides access to all Perl keywords, regardless of this
111pragma.)
112
113=head2 Lexical effect
114
115Like other pragmas (C<use strict>, for example), features have a lexical
116effect.  C<use feature qw(foo)> will only make the feature "foo" available
117from that point to the end of the enclosing block.
118
119    {
120        use feature 'say';
121        say "say is available here";
122    }
123    print "But not here.\n";
124
125=head2 C<no feature>
126
127Features can also be turned off by using C<no feature "foo">.  This too
128has lexical effect.
129
130    use feature 'say';
131    say "say is available here";
132    {
133        no feature 'say';
134        print "But not here.\n";
135    }
136    say "Yet it is here.";
137
138C<no feature> with no features specified will reset to the default group.  To
139disable I<all> features (an unusual request!) use C<no feature ':all'>.
140
141=head1 AVAILABLE FEATURES
142
143=head2 The 'say' feature
144
145C<use feature 'say'> tells the compiler to enable the Raku-inspired
146C<say> function.
147
148See L<perlfunc/say> for details.
149
150This feature is available starting with Perl 5.10.
151
152=head2 The 'state' feature
153
154C<use feature 'state'> tells the compiler to enable C<state>
155variables.
156
157See L<perlsub/"Persistent Private Variables"> for details.
158
159This feature is available starting with Perl 5.10.
160
161=head2 The 'switch' feature
162
163B<WARNING>: This feature is still experimental and the implementation may
164change or be removed in future versions of Perl.  For this reason, Perl will
165warn when you use the feature, unless you have explicitly disabled the warning:
166
167    no warnings "experimental::smartmatch";
168
169C<use feature 'switch'> tells the compiler to enable the Raku
170given/when construct.
171
172See L<perlsyn/"Switch Statements"> for details.
173
174This feature is available starting with Perl 5.10.
175
176=head2 The 'unicode_strings' feature
177
178C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
179in all string operations executed within its scope (unless they are also
180within the scope of either C<use locale> or C<use bytes>).  The same applies
181to all regular expressions compiled within the scope, even if executed outside
182it.  It does not change the internal representation of strings, but only how
183they are interpreted.
184
185C<no feature 'unicode_strings'> tells the compiler to use the traditional
186Perl rules wherein the native character set rules is used unless it is
187clear to Perl that Unicode is desired.  This can lead to some surprises
188when the behavior suddenly changes.  (See
189L<perlunicode/The "Unicode Bug"> for details.)  For this reason, if you are
190potentially using Unicode in your program, the
191C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
192
193This feature is available starting with Perl 5.12; was almost fully
194implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>;
195was extended further in Perl 5.26 to cover L<the range
196operator|perlop/Range Operators>; and was extended again in Perl 5.28 to
197cover L<special-cased whitespace splitting|perlfunc/split>.
198
199=head2 The 'unicode_eval' and 'evalbytes' features
200
201Together, these two features are intended to replace the legacy string
202C<eval> function, which behaves problematically in some instances.  They are
203available starting with Perl 5.16, and are enabled by default by a
204S<C<use 5.16>> or higher declaration.
205
206C<unicode_eval> changes the behavior of plain string C<eval> to work more
207consistently, especially in the Unicode world.  Certain (mis)behaviors
208couldn't be changed without breaking some things that had come to rely on
209them, so the feature can be enabled and disabled.  Details are at
210L<perlfunc/Under the "unicode_eval" feature>.
211
212C<evalbytes> is like string C<eval>, but operating on a byte stream that is
213not UTF-8 encoded.  Details are at L<perlfunc/evalbytes EXPR>.  Without a
214S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in
215the current scope, you can still access it by instead writing
216C<CORE::evalbytes>.
217
218=head2 The 'current_sub' feature
219
220This provides the C<__SUB__> token that returns a reference to the current
221subroutine or C<undef> outside of a subroutine.
222
223This feature is available starting with Perl 5.16.
224
225=head2 The 'array_base' feature
226
227This feature supported the legacy C<$[> variable.  See L<perlvar/$[>.
228It was on by default but disabled under C<use v5.16> (see
229L</IMPLICIT LOADING>, below) and unavailable since perl 5.30.
230
231This feature is available under this name starting with Perl 5.16.  In
232previous versions, it was simply on all the time, and this pragma knew
233nothing about it.
234
235=head2 The 'fc' feature
236
237C<use feature 'fc'> tells the compiler to enable the C<fc> function,
238which implements Unicode casefolding.
239
240See L<perlfunc/fc> for details.
241
242This feature is available from Perl 5.16 onwards.
243
244=head2 The 'lexical_subs' feature
245
246In Perl versions prior to 5.26, this feature enabled
247declaration of subroutines via C<my sub foo>, C<state sub foo>
248and C<our sub foo> syntax.  See L<perlsub/Lexical Subroutines> for details.
249
250This feature is available from Perl 5.18 onwards.  From Perl 5.18 to 5.24,
251it was classed as experimental, and Perl emitted a warning for its
252usage, except when explicitly disabled:
253
254  no warnings "experimental::lexical_subs";
255
256As of Perl 5.26, use of this feature no longer triggers a warning, though
257the C<experimental::lexical_subs> warning category still exists (for
258compatibility with code that disables it).  In addition, this syntax is
259not only no longer experimental, but it is enabled for all Perl code,
260regardless of what feature declarations are in scope.
261
262=head2 The 'postderef' and 'postderef_qq' features
263
264The 'postderef_qq' feature extends the applicability of L<postfix
265dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array
266and scalar dereference are available in double-quotish interpolations. For
267example, it makes the following two statements equivalent:
268
269  my $s = "[@{ $h->{a} }]";
270  my $s = "[$h->{a}->@*]";
271
272This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it
273was classed as experimental, and Perl emitted a warning for its
274usage, except when explicitly disabled:
275
276  no warnings "experimental::postderef";
277
278As of Perl 5.24, use of this feature no longer triggers a warning, though
279the C<experimental::postderef> warning category still exists (for
280compatibility with code that disables it).
281
282The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
283postfix dereference syntax outside double-quotish interpolations. In those
284versions, using it triggered the C<experimental::postderef> warning in the
285same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is
286not only no longer experimental, but it is enabled for all Perl code,
287regardless of what feature declarations are in scope.
288
289=head2 The 'signatures' feature
290
291B<WARNING>: This feature is still experimental and the implementation may
292change or be removed in future versions of Perl.  For this reason, Perl will
293warn when you use the feature, unless you have explicitly disabled the warning:
294
295    no warnings "experimental::signatures";
296
297This enables unpacking of subroutine arguments into lexical variables
298by syntax such as
299
300    sub foo ($left, $right) {
301	return $left + $right;
302    }
303
304See L<perlsub/Signatures> for details.
305
306This feature is available from Perl 5.20 onwards.
307
308=head2 The 'refaliasing' feature
309
310B<WARNING>: This feature is still experimental and the implementation may
311change or be removed in future versions of Perl.  For this reason, Perl will
312warn when you use the feature, unless you have explicitly disabled the warning:
313
314    no warnings "experimental::refaliasing";
315
316This enables aliasing via assignment to references:
317
318    \$a = \$b; # $a and $b now point to the same scalar
319    \@a = \@b; #                     to the same array
320    \%a = \%b;
321    \&a = \&b;
322    foreach \%hash (@array_of_hash_refs) {
323        ...
324    }
325
326See L<perlref/Assigning to References> for details.
327
328This feature is available from Perl 5.22 onwards.
329
330=head2 The 'bitwise' feature
331
332This makes the four standard bitwise operators (C<& | ^ ~>) treat their
333operands consistently as numbers, and introduces four new dotted operators
334(C<&. |. ^. ~.>) that treat their operands consistently as strings.  The
335same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
336
337See L<perlop/Bitwise String Operators> for details.
338
339This feature is available from Perl 5.22 onwards.  Starting in Perl 5.28,
340C<use v5.28> will enable the feature.  Before 5.28, it was still
341experimental and would emit a warning in the "experimental::bitwise"
342category.
343
344=head2 The 'declared_refs' feature
345
346B<WARNING>: This feature is still experimental and the implementation may
347change or be removed in future versions of Perl.  For this reason, Perl will
348warn when you use the feature, unless you have explicitly disabled the warning:
349
350    no warnings "experimental::declared_refs";
351
352This allows a reference to a variable to be declared with C<my>, C<state>,
353our C<our>, or localized with C<local>.  It is intended mainly for use in
354conjunction with the "refaliasing" feature.  See L<perlref/Declaring a
355Reference to a Variable> for examples.
356
357This feature is available from Perl 5.26 onwards.
358
359=head2 The 'isa' feature
360
361B<WARNING>: This feature is still experimental and the implementation may
362change or be removed in future versions of Perl.  For this reason, Perl will
363warn when you use the feature, unless you have explicitly disabled the warning:
364
365    no warnings "experimental::isa";
366
367This allows the use of the C<isa> infix operator, which tests whether the
368scalar given by the left operand is an object of the class given by the
369right operand. See L<perlop/Class Instance Operator> for more details.
370
371This feature is available from Perl 5.32 onwards.
372
373=head2 The 'indirect' feature
374
375This feature allows the use of L<indirect object
376syntax|perlobj/Indirect Object Syntax> for method calls, e.g.  C<new
377Foo 1, 2;>. It is enabled by default, but can be turned off to
378disallow indirect object syntax.
379
380This feature is available under this name from Perl 5.32 onwards. In
381previous versions, it was simply on all the time.  To disallow (or
382warn on) indirect object syntax on older Perls, see the L<indirect>
383CPAN module.
384
385=head2 The 'multidimensional' feature
386
387This feature enables multidimensional array emulation, a perl 4 (or
388earlier) feature that was used to emulate multidimensional arrays with
389hashes.  This works by converting code like C<< $foo{$x, $y} >> into
390C<< $foo{join($;, $x, $y)} >>.  It is enabled by default, but can be
391turned off to disable multidimensional array emulation.
392
393When this feature is disabled the syntax that is normally replaced
394will report a compilation error.
395
396This feature is available under this name from Perl 5.34 onwards. In
397previous versions, it was simply on all the time.
398
399You can use the L<multidimensional> module on CPAN to disable
400multidimensional array emulation for older versions of Perl.
401
402=head2 The 'bareword_filehandles' feature.
403
404This feature enables bareword filehandles for builtin functions
405operations, a generally discouraged practice.  It is enabled by
406default, but can be turned off to disable bareword filehandles, except
407for the exceptions listed below.
408
409The perl built-in filehandles C<STDIN>, C<STDOUT>, C<STDERR>, C<DATA>,
410C<ARGV>, C<ARGVOUT> and the special C<_> are always enabled.
411
412This feature is enabled under this name from Perl 5.34 onwards.  In
413previous versions it was simply on all the time.
414
415You can use the L<bareword::filehandles> module on CPAN to disable
416bareword filehandles for older versions of perl.
417
418=head2 The 'try' feature.
419
420B<WARNING>: This feature is still experimental and the implementation may
421change or be removed in future versions of Perl.  For this reason, Perl will
422warn when you use the feature, unless you have explicitly disabled the warning:
423
424    no warnings "experimental::try";
425
426This feature enables the C<try> and C<catch> syntax, which allows exception
427handling, where exceptions thrown from the body of the block introduced with
428C<try> are caught by executing the body of the C<catch> block.
429
430For more information, see L<perlsyn/"Try Catch Exception Handling">.
431
432=head1 FEATURE BUNDLES
433
434It's possible to load multiple features together, using
435a I<feature bundle>.  The name of a feature bundle is prefixed with
436a colon, to distinguish it from an actual feature.
437
438  use feature ":5.10";
439
440The following feature bundles are available:
441
442  bundle    features included
443  --------- -----------------
444  :default  indirect multidimensional
445            bareword_filehandles
446
447  :5.10     bareword_filehandles indirect
448            multidimensional say state switch
449
450  :5.12     bareword_filehandles indirect
451            multidimensional say state switch
452            unicode_strings
453
454  :5.14     bareword_filehandles indirect
455            multidimensional say state switch
456            unicode_strings
457
458  :5.16     bareword_filehandles current_sub evalbytes
459            fc indirect multidimensional say state
460            switch unicode_eval unicode_strings
461
462  :5.18     bareword_filehandles current_sub evalbytes
463            fc indirect multidimensional say state
464            switch unicode_eval unicode_strings
465
466  :5.20     bareword_filehandles current_sub evalbytes
467            fc indirect multidimensional say state
468            switch unicode_eval unicode_strings
469
470  :5.22     bareword_filehandles current_sub evalbytes
471            fc indirect multidimensional say state
472            switch unicode_eval unicode_strings
473
474  :5.24     bareword_filehandles current_sub evalbytes
475            fc indirect multidimensional postderef_qq
476            say state switch unicode_eval
477            unicode_strings
478
479  :5.26     bareword_filehandles current_sub evalbytes
480            fc indirect multidimensional postderef_qq
481            say state switch unicode_eval
482            unicode_strings
483
484  :5.28     bareword_filehandles bitwise current_sub
485            evalbytes fc indirect multidimensional
486            postderef_qq say state switch unicode_eval
487            unicode_strings
488
489  :5.30     bareword_filehandles bitwise current_sub
490            evalbytes fc indirect multidimensional
491            postderef_qq say state switch unicode_eval
492            unicode_strings
493
494  :5.32     bareword_filehandles bitwise current_sub
495            evalbytes fc indirect multidimensional
496            postderef_qq say state switch unicode_eval
497            unicode_strings
498
499  :5.34     bareword_filehandles bitwise current_sub
500            evalbytes fc indirect multidimensional
501            postderef_qq say state switch unicode_eval
502            unicode_strings
503
504The C<:default> bundle represents the feature set that is enabled before
505any C<use feature> or C<no feature> declaration.
506
507Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
508no effect.  Feature bundles are guaranteed to be the same for all sub-versions.
509
510  use feature ":5.14.0";    # same as ":5.14"
511  use feature ":5.14.1";    # same as ":5.14"
512
513=head1 IMPLICIT LOADING
514
515Instead of loading feature bundles by name, it is easier to let Perl do
516implicit loading of a feature bundle for you.
517
518There are two ways to load the C<feature> pragma implicitly:
519
520=over 4
521
522=item *
523
524By using the C<-E> switch on the Perl command-line instead of C<-e>.
525That will enable the feature bundle for that version of Perl in the
526main compilation unit (that is, the one-liner that follows C<-E>).
527
528=item *
529
530By explicitly requiring a minimum Perl version number for your program, with
531the C<use VERSION> construct.  That is,
532
533    use v5.10.0;
534
535will do an implicit
536
537    no feature ':all';
538    use feature ':5.10';
539
540and so on.  Note how the trailing sub-version
541is automatically stripped from the
542version.
543
544But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
545
546    use 5.010;
547
548with the same effect.
549
550If the required version is older than Perl 5.10, the ":default" feature
551bundle is automatically loaded instead.
552
553Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version)
554also does the equivalent of C<use strict>; see L<perlfunc/use> for details.
555
556=back
557
558=cut
559
560sub import {
561    shift;
562
563    if (!@_) {
564        croak("No features specified");
565    }
566
567    __common(1, @_);
568}
569
570sub unimport {
571    shift;
572
573    # A bare C<no feature> should reset to the default bundle
574    if (!@_) {
575	$^H &= ~($hint_uni8bit|$hint_mask);
576	return;
577    }
578
579    __common(0, @_);
580}
581
582
583sub __common {
584    my $import = shift;
585    my $bundle_number = $^H & $hint_mask;
586    my $features = $bundle_number != $hint_mask
587      && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
588    if ($features) {
589	# Features are enabled implicitly via bundle hints.
590	# Delete any keys that may be left over from last time.
591	delete @^H{ values(%feature) };
592	$^H |= $hint_mask;
593	for (@$features) {
594	    $^H{$feature{$_}} = 1;
595	    $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
596	}
597    }
598    while (@_) {
599        my $name = shift;
600        if (substr($name, 0, 1) eq ":") {
601            my $v = substr($name, 1);
602            if (!exists $feature_bundle{$v}) {
603                $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
604                if (!exists $feature_bundle{$v}) {
605                    unknown_feature_bundle(substr($name, 1));
606                }
607            }
608            unshift @_, @{$feature_bundle{$v}};
609            next;
610        }
611        if (!exists $feature{$name}) {
612            if (exists $noops{$name}) {
613                next;
614            }
615            if (!$import && exists $removed{$name}) {
616                next;
617            }
618            unknown_feature($name);
619        }
620	if ($import) {
621	    $^H{$feature{$name}} = 1;
622	    $^H |= $hint_uni8bit if $name eq 'unicode_strings';
623	} else {
624            delete $^H{$feature{$name}};
625            $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
626        }
627    }
628}
629
630sub unknown_feature {
631    my $feature = shift;
632    croak(sprintf('Feature "%s" is not supported by Perl %vd',
633            $feature, $^V));
634}
635
636sub unknown_feature_bundle {
637    my $feature = shift;
638    croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
639            $feature, $^V));
640}
641
642sub croak {
643    require Carp;
644    Carp::croak(@_);
645}
646
6471;
648
649# ex: set ro:
650