package feature;
-our $VERSION = '1.17';
+our $VERSION = '1.21';
# (feature name) => (internal name, used in %^H)
my %feature = (
"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
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
=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 :