X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/b12c4a8a51f322667e5fb7ed508edf25d74ed604..f4c2a127695c97f0d85d468a0cc4747762c25841:/lib/feature.pm

diff --git a/lib/feature.pm b/lib/feature.pm
index cd5a66a..2ee1018 100644
--- a/lib/feature.pm
+++ b/lib/feature.pm
@@ -1,6 +1,6 @@
 package feature;
 
-our $VERSION = '1.17';
+our $VERSION = '1.21';
 
 # (feature name) => (internal name, used in %^H)
 my %feature = (
@@ -22,6 +22,8 @@ my %feature_bundle = (
     "5.11" => [qw(switch say state unicode_strings)],
     "5.12" => [qw(switch say state unicode_strings)],
     "5.13" => [qw(switch say state unicode_strings)],
+    "5.14" => [qw(switch say state unicode_strings)],
+    "5.15" => [qw(switch say state unicode_strings)],
 );
 
 # special case
@@ -53,7 +55,9 @@ 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<use feature 'foo'>, and will be parsed
-only when the appropriate feature pragma is in scope.
+only when the appropriate feature pragma is in scope. (Nevertheless, the
+C<CORE::> prefix provides access to all Perl keywords, regardless of this
+pragma.)
 
 =head2 Lexical effect
 
@@ -105,23 +109,44 @@ See L<perlsub/"Persistent Private Variables"> for details.
 
 =head2 the 'unicode_strings' feature
 
-C<use feature 'unicode_strings'> tells the compiler to treat
-all strings outside of C<use locale> and C<use bytes> as Unicode. It is
-available starting with Perl 5.11.3, but is not fully implemented.
+C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
+in all string operations executed within its scope (unless they are also
+within the scope of either C<use locale> or C<use bytes>).  The same applies
+to all regular expressions compiled within the scope, even if executed outside
+it.
 
-See L<perlunicode/The "Unicode Bug"> for details.
+C<no feature 'unicode_strings'> tells the compiler to use the traditional
+Perl semantics wherein the native character set semantics is used unless it is
+clear to Perl that Unicode is desired.  This can lead to some surprises
+when the behavior suddenly changes.  (See
+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.
 
 =head1 FEATURE BUNDLES
 
 It's possible to load a whole slew of features in one go, 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, the
-only feature bundle is C<use feature ":5.10"> which is equivalent
-to C<use feature qw(switch say state)>.
+only feature bundles correspond to Perl releases, e.g. C<use feature
+":5.10"> which is equivalent to C<use feature qw(switch say state)>.
+
+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)>.
 
-Specifying sub-versions such as the C<0> in C<5.10.0> in feature bundles has
+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.
 
+Note that instead of using release-based feature bundles it is usually
+better, and shorter, to use implicit loading as described below.
+
 =head1 IMPLICIT LOADING
 
 There are two ways to load the C<feature> pragma implicitly :