package feature; our $VERSION = '1.17'; # (feature name) => (internal name, used in %^H) my %feature = ( switch => 'feature_switch', say => "feature_say", state => "feature_state", unicode_strings => "feature_unicode", ); # This gets set (for now) in $^H as well as in %^H, # for runtime speed of the uc/lc/ucfirst/lcfirst functions. # See HINT_UNI_8_BIT in perl.h. our $hint_uni8bit = 0x00000800; # NB. the latest bundle must be loaded by the -E switch (see toke.c) my %feature_bundle = ( "5.10" => [qw(switch say state)], "5.11" => [qw(switch say state unicode_strings)], "5.12" => [qw(switch say state unicode_strings)], "5.13" => [qw(switch say state unicode_strings)], ); # special case $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"}; # TODO: # - think about versioned features (use feature switch => 2) =head1 NAME feature - Perl pragma to enable new features =head1 SYNOPSIS use feature qw(switch say); given ($foo) { when (1) { say "\$foo == 1" } when ([2,3]) { say "\$foo == 2 || \$foo == 3" } when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" } when ($_ > 100) { say "\$foo > 100" } default { say "None of the above" } } use feature ':5.10'; # loads all features available in perl 5.10 =head1 DESCRIPTION It is usually impossible to add new syntax to Perl without breaking some existing programs. This pragma provides a way to minimize that risk. New syntactic constructs, or new semantic meanings to older constructs, can be enabled by C, and will be parsed only when the appropriate feature pragma is in scope. =head2 Lexical effect Like other pragmas (C, for example), features have a lexical effect. C will only make the feature "foo" available from that point to the end of the enclosing block. { use feature 'say'; say "say is available here"; } print "But not here.\n"; =head2 C Features can also be turned off by using C. This too has lexical effect. use feature 'say'; say "say is available here"; { no feature 'say'; print "But not here.\n"; } say "Yet it is here."; C with no features specified will turn off all features. =head2 The 'switch' feature C tells the compiler to enable the Perl 6 given/when construct. See L for details. =head2 The 'say' feature C tells the compiler to enable the Perl 6 C function. See L for details. =head2 the 'state' feature C tells the compiler to enable C variables. See L for details. =head2 the 'unicode_strings' feature C tells the compiler to treat all strings outside of C and C as Unicode. It is available starting with Perl 5.11.3. See L for details. =head1 FEATURE BUNDLES It's possible to load a whole slew of features in one go, using a I. The name of a feature bundle is prefixed with a colon, to distinguish it from an actual feature. At present, the only feature bundle is C which is equivalent to C. Specifying sub-versions such as the C<0> in C<5.10.0> in feature bundles has no effect: feature bundles are guaranteed to be the same for all sub-versions. =head1 IMPLICIT LOADING There are two ways to load the C pragma implicitly : =over 4 =item * By using the C<-E> switch on the command-line instead of C<-e>. It enables all available features in the main compilation unit (that is, the one-liner.) =item * By requiring explicitly a minimal Perl version number for your program, with the C construct, and when the version is higher than or equal to 5.10.0. That is, use 5.10.0; will do an implicit use feature ':5.10'; and so on. Note how the trailing sub-version is automatically stripped from the version. But to avoid portability warnings (see L), you may prefer: use 5.010; with the same effect. =back =cut sub import { my $class = shift; if (@_ == 0) { croak("No features specified"); } while (@_) { my $name = shift(@_); if (substr($name, 0, 1) eq ":") { my $v = substr($name, 1); if (!exists $feature_bundle{$v}) { $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/; if (!exists $feature_bundle{$v}) { unknown_feature_bundle(substr($name, 1)); } } unshift @_, @{$feature_bundle{$v}}; next; } if (!exists $feature{$name}) { unknown_feature($name); } $^H{$feature{$name}} = 1; $^H |= $hint_uni8bit if $name eq 'unicode_strings'; } } sub unimport { my $class = shift; # A bare C should disable *all* features if (!@_) { delete @^H{ values(%feature) }; $^H &= ~ $hint_uni8bit; return; } while (@_) { my $name = shift; if (substr($name, 0, 1) eq ":") { my $v = substr($name, 1); if (!exists $feature_bundle{$v}) { $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/; if (!exists $feature_bundle{$v}) { unknown_feature_bundle(substr($name, 1)); } } unshift @_, @{$feature_bundle{$v}}; next; } if (!exists($feature{$name})) { unknown_feature($name); } else { delete $^H{$feature{$name}}; $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings'; } } } sub unknown_feature { my $feature = shift; croak(sprintf('Feature "%s" is not supported by Perl %vd', $feature, $^V)); } sub unknown_feature_bundle { my $feature = shift; croak(sprintf('Feature bundle "%s" is not supported by Perl %vd', $feature, $^V)); } sub croak { require Carp; Carp::croak(@_); } 1;