Revise feature.pm documentation

1 files changed, 99 insertions, 75 deletions

diff --git a/lib/feature.pm b/lib/feature.pm
index ac7a23c9c5..4cfa27ffdc 100644
--- a/lib/feature.pm
+++ b/lib/feature.pm
@@ -47,15 +47,17 @@ feature - Perl pragma to enable new features
 
     use feature qw(say switch);
     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" }
+        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
 
+    use v5.10;           # implicitly loads :5.10 feature bundle
+
 =head1 DESCRIPTION
 
 It is usually impossible to add new syntax to Perl without breaking
@@ -93,20 +95,26 @@ has lexical effect.
 
 C<no feature> with no features specified will turn off all features.
 
+=head1 AVAILABLE FEATURES
+
 =head2 The 'say' feature
 
-C<use feature 'say'> tells the compiler to enable the Perl 6
+C<use feature 'say'> tells the compiler to enable the Perl 6 style
 C<say> function.
 
 See L<perlfunc/say> for details.
 
-=head2 the 'state' feature
+This feature is available starting with Perl 5.10.
+
+=head2 The 'state' feature
 
 C<use feature 'state'> tells the compiler to enable C<state>
 variables.
 
 See L<perlsub/"Persistent Private Variables"> for details.
 
+This feature is available starting with Perl 5.10.
+
 =head2 The 'switch' feature
 
 C<use feature 'switch'> tells the compiler to enable the Perl 6
@@ -114,7 +122,9 @@ given/when construct.
 
 See L<perlsyn/"Switch statements"> for details.
 
-=head2 the 'unicode_strings' feature
+This feature is available starting with Perl 5.10.
+
+=head2 The 'unicode_strings' feature
 
 C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
 in all string operations executed within its scope (unless they are also
@@ -130,10 +140,10 @@ L<perlunicode/The "Unicode Bug"> for details.)  For this reason, if you are
 potentially using Unicode in your program, the
 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
 
-This subpragma is available starting with Perl 5.11.3, but was not fully
-implemented until 5.13.8.
+This feature is available starting with Perl 5.12, but was not fully
+implemented until Perl 5.14.
 
-=head2 the 'unicode_eval' and 'evalbytes' features
+=head2 The 'unicode_eval' and 'evalbytes' features
 
 Under the C<unicode_eval> feature, Perl's C<eval> function, when passed a
 string, will evaluate it as a string of characters, ignoring any
@@ -189,45 +199,57 @@ This feature is available starting with Perl 5.16.
 
 =head1 FEATURE BUNDLES
 
-It's possible to load a whole slew of features in one go, using
+It's possible to load multiple features together, using
 a I<feature bundle>. The name of a feature bundle is prefixed with
-a colon, to distinguish it from an actual feature. At present, most
-feature bundles correspond to Perl releases, e.g. C<use feature
-":5.10"> which is equivalent to C<use feature qw(switch say state)>. The
-only bundle that does not follow this convention is ":default", which is
-currently empty.
-
-By convention, the feature bundle for any given Perl release includes
-the features of previous releases, down to and including 5.10, the
-first official release to provide this facility. Since Perl 5.12
-only provides one new feature, C<unicode_strings>, and Perl 5.14
-provides none, C<use feature ":5.14"> is equivalent to C<use feature
-qw(switch say state unicode_strings)>.
+a colon, to distinguish it from an actual feature.
+
+  use feature ":5.10";
+
+The following feature bundles are available:
+
+  bundle    features included
+  --------- -----------------
+  :default  none
+
+  :5.10     say state switch
+
+  :5.12     say state switch unicode_strings
+
+  :5.14     say state switch unicode_strings
+
+  :5.16     say state switch unicode_strings
+            unicode_eval evalbytes current_sub
+
+The empty C<:default> bundle is provided for future
+backwards-compatibility when using L<implicit loading|/IMPLICIT LOADING>.
 
 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
-no effect: feature bundles are guaranteed to be the same for all sub-versions.
+no effect. Feature bundles are guaranteed to be the same for all sub-versions.
 
-Note that instead of using release-based feature bundles it is usually
-better, and shorter, to use implicit loading as described below.
+  use feature ":5.14.0";    # same as ":5.14"
+  use feature ":5.14.1";    # same as ":5.14"
 
 =head1 IMPLICIT LOADING
 
-There are two ways to load the C<feature> pragma implicitly :
+Instead of loading feature bundles by name, it is easier to let Perl do
+implicit loading of a feature bundle for you.
+
+There are two ways to load the C<feature> 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.)
+By using the C<-E> switch on the Perl command-line instead of C<-e>.
+That will enable the feature bundle for that version of Perl in the
+main compilation unit (that is, the one-liner that follows C<-E>).
 
 =item *
 
-By requiring explicitly a minimal Perl version number for your program, with
-the C<use VERSION> construct, and when the version is higher than or equal to
-5.10.0. That is,
+By explicitly requiring a minimum Perl version number for your program, with
+the C<use VERSION> construct. That is,
 
-    use 5.10.0;
+    use v5.10.0;
 
 will do an implicit
 
@@ -243,8 +265,10 @@ But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
 
 with the same effect.
 
-For versions below 5.010, the ":default" feature bundle is automatically
-loaded, but it is currently empty and has no effect.
+If the required version is older than Perl 5.10, the ":default" feature
+bundle is automatically loaded instead. It is currently empty and has no
+effect, but may be used in the future to support backwards
+compatibility.
 
 =back
 
@@ -253,25 +277,25 @@ loaded, but it is currently empty and has no effect.
 sub import {
     my $class = shift;
     if (@_ == 0) {
-	croak("No features specified");
+        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;
+        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';
     }
 }
@@ -281,44 +305,44 @@ sub unimport {
 
     # A bare C<no feature> should disable *all* features
     if (!@_) {
-	delete @^H{ values(%feature) };
+        delete @^H{ values(%feature) };
         $^H &= ~ $hint_uni8bit;
-	return;
+        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}};
+        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));
+            $feature, $^V));
 }
 
 sub unknown_feature_bundle {
     my $feature = shift;
     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
-	    $feature, $^V));
+            $feature, $^V));
 }
 
 sub croak {