This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
OS2-Process/Process.pm: Fix broken pod links
[perl5.git] / lib / feature.pm
CommitLineData
0d863452
RH
1package feature;
2
8891dd8d 3our $VERSION = '1.21';
0d863452
RH
4
5# (feature name) => (internal name, used in %^H)
6my %feature = (
1863b879
RGS
7 switch => 'feature_switch',
8 say => "feature_say",
9 state => "feature_state",
10 unicode_strings => "feature_unicode",
bc9b29db
RH
11);
12
1863b879
RGS
13# This gets set (for now) in $^H as well as in %^H,
14# for runtime speed of the uc/lc/ucfirst/lcfirst functions.
b0f41c9d 15# See HINT_UNI_8_BIT in perl.h.
1863b879
RGS
16our $hint_uni8bit = 0x00000800;
17
13a7998c
RGS
18# NB. the latest bundle must be loaded by the -E switch (see toke.c)
19
bc9b29db 20my %feature_bundle = (
82cfb3a2 21 "5.10" => [qw(switch say state)],
1863b879 22 "5.11" => [qw(switch say state unicode_strings)],
b7569deb 23 "5.12" => [qw(switch say state unicode_strings)],
e836a73b 24 "5.13" => [qw(switch say state unicode_strings)],
11ca38a1 25 "5.14" => [qw(switch say state unicode_strings)],
8891dd8d 26 "5.15" => [qw(switch say state unicode_strings)],
0d863452 27);
d052521a 28
82cfb3a2
S
29# special case
30$feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
7dfde25d 31
0d863452 32# TODO:
1c321dc6 33# - think about versioned features (use feature switch => 2)
0d863452
RH
34
35=head1 NAME
36
e1b711da 37feature - Perl pragma to enable new features
0d863452
RH
38
39=head1 SYNOPSIS
40
bc9b29db 41 use feature qw(switch say);
0d863452 42 given ($foo) {
bc9b29db
RH
43 when (1) { say "\$foo == 1" }
44 when ([2,3]) { say "\$foo == 2 || \$foo == 3" }
45 when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
46 when ($_ > 100) { say "\$foo > 100" }
47 default { say "None of the above" }
0d863452
RH
48 }
49
ec488c7f
RGS
50 use feature ':5.10'; # loads all features available in perl 5.10
51
0d863452
RH
52=head1 DESCRIPTION
53
54It is usually impossible to add new syntax to Perl without breaking
55some existing programs. This pragma provides a way to minimize that
1863b879
RGS
56risk. New syntactic constructs, or new semantic meanings to older
57constructs, can be enabled by C<use feature 'foo'>, and will be parsed
4a904372
FC
58only when the appropriate feature pragma is in scope. (Nevertheless, the
59C<CORE::> prefix provides access to all Perl keywords, regardless of this
60pragma.)
0d863452 61
9eb27be9
RGS
62=head2 Lexical effect
63
64Like other pragmas (C<use strict>, for example), features have a lexical
5e36ed56 65effect. C<use feature qw(foo)> will only make the feature "foo" available
9eb27be9
RGS
66from that point to the end of the enclosing block.
67
68 {
69 use feature 'say';
70 say "say is available here";
71 }
72 print "But not here.\n";
73
5e36ed56
RGS
74=head2 C<no feature>
75
76Features can also be turned off by using C<no feature "foo">. This too
77has lexical effect.
78
79 use feature 'say';
80 say "say is available here";
81 {
82 no feature 'say';
83 print "But not here.\n";
84 }
85 say "Yet it is here.";
86
87C<no feature> with no features specified will turn off all features.
88
0d863452
RH
89=head2 The 'switch' feature
90
91C<use feature 'switch'> tells the compiler to enable the Perl 6
9eb27be9 92given/when construct.
0d863452
RH
93
94See L<perlsyn/"Switch statements"> for details.
95
0d863452
RH
96=head2 The 'say' feature
97
98C<use feature 'say'> tells the compiler to enable the Perl 6
9eb27be9 99C<say> function.
0d863452
RH
100
101See L<perlfunc/say> for details.
102
712d05cf
RGS
103=head2 the 'state' feature
104
105C<use feature 'state'> tells the compiler to enable C<state>
9eb27be9 106variables.
712d05cf 107
e60bcc8b
RGS
108See L<perlsub/"Persistent Private Variables"> for details.
109
1863b879
RGS
110=head2 the 'unicode_strings' feature
111
20db7501
KW
112C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
113in all string operations executed within its scope (unless they are also
114within the scope of either C<use locale> or C<use bytes>). The same applies
115to all regular expressions compiled within the scope, even if executed outside
116it.
117
118C<no feature 'unicode_strings'> tells the compiler to use the traditional
119Perl semantics wherein the native character set semantics is used unless it is
120clear to Perl that Unicode is desired. This can lead to some surprises
121when the behavior suddenly changes. (See
122L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
123potentially using Unicode in your program, the
124C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
125
126This subpragma is available starting with Perl 5.11.3, but was not fully
127implemented until 5.13.8.
1863b879 128
bc9b29db
RH
129=head1 FEATURE BUNDLES
130
131It's possible to load a whole slew of features in one go, using
132a I<feature bundle>. The name of a feature bundle is prefixed with
133a colon, to distinguish it from an actual feature. At present, the
a3a91442
JV
134only feature bundles correspond to Perl releases, e.g. C<use feature
135":5.10"> which is equivalent to C<use feature qw(switch say state)>.
8fd870d9 136
a3a91442
JV
137By convention, the feature bundle for any given Perl release includes
138the features of previous releases, down to and including 5.10, the
139first official release to provide this facility. Since Perl 5.12
140only provides one new feature, C<unicode_strings>, and Perl 5.14
141provides none, C<use feature ":5.14"> is equivalent to C<use feature
142qw(switch say state unicode_strings)>.
143
144Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
82cfb3a2 145no effect: feature bundles are guaranteed to be the same for all sub-versions.
bc9b29db 146
a3a91442
JV
147Note that instead of using release-based feature bundles it is usually
148better, and shorter, to use implicit loading as described below.
149
7dfde25d
RGS
150=head1 IMPLICIT LOADING
151
152There are two ways to load the C<feature> pragma implicitly :
153
154=over 4
155
156=item *
157
158By using the C<-E> switch on the command-line instead of C<-e>. It enables
159all available features in the main compilation unit (that is, the one-liner.)
160
161=item *
162
163By requiring explicitly a minimal Perl version number for your program, with
164the C<use VERSION> construct, and when the version is higher than or equal to
8d115822 1655.10.0. That is,
7dfde25d 166
8d115822 167 use 5.10.0;
7dfde25d
RGS
168
169will do an implicit
170
82cfb3a2 171 use feature ':5.10';
7dfde25d 172
82cfb3a2
S
173and so on. Note how the trailing sub-version is automatically stripped from the
174version.
7dfde25d 175
8d115822
RB
176But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
177
178 use 5.010;
179
180with the same effect.
181
7dfde25d
RGS
182=back
183
0d863452
RH
184=cut
185
186sub import {
0d863452
RH
187 my $class = shift;
188 if (@_ == 0) {
0d863452
RH
189 croak("No features specified");
190 }
191 while (@_) {
192 my $name = shift(@_);
89c3975a
RGS
193 if (substr($name, 0, 1) eq ":") {
194 my $v = substr($name, 1);
7be54ea7 195 if (!exists $feature_bundle{$v}) {
82cfb3a2
S
196 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
197 if (!exists $feature_bundle{$v}) {
198 unknown_feature_bundle(substr($name, 1));
199 }
bc9b29db 200 }
7be54ea7 201 unshift @_, @{$feature_bundle{$v}};
bc9b29db
RH
202 next;
203 }
0d863452 204 if (!exists $feature{$name}) {
b42943c4 205 unknown_feature($name);
0d863452
RH
206 }
207 $^H{$feature{$name}} = 1;
1863b879 208 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
0d863452
RH
209 }
210}
211
212sub unimport {
213 my $class = shift;
214
215 # A bare C<no feature> should disable *all* features
bc9b29db
RH
216 if (!@_) {
217 delete @^H{ values(%feature) };
1863b879 218 $^H &= ~ $hint_uni8bit;
bc9b29db
RH
219 return;
220 }
221
222 while (@_) {
223 my $name = shift;
89c3975a
RGS
224 if (substr($name, 0, 1) eq ":") {
225 my $v = substr($name, 1);
7be54ea7 226 if (!exists $feature_bundle{$v}) {
82cfb3a2
S
227 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
228 if (!exists $feature_bundle{$v}) {
229 unknown_feature_bundle(substr($name, 1));
230 }
bc9b29db 231 }
7be54ea7 232 unshift @_, @{$feature_bundle{$v}};
bc9b29db
RH
233 next;
234 }
0d863452 235 if (!exists($feature{$name})) {
b42943c4 236 unknown_feature($name);
0d863452
RH
237 }
238 else {
239 delete $^H{$feature{$name}};
1863b879 240 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
0d863452
RH
241 }
242 }
0d863452
RH
243}
244
b42943c4
RGS
245sub unknown_feature {
246 my $feature = shift;
247 croak(sprintf('Feature "%s" is not supported by Perl %vd',
248 $feature, $^V));
249}
250
251sub unknown_feature_bundle {
252 my $feature = shift;
253 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
254 $feature, $^V));
255}
256
257sub croak {
258 require Carp;
259 Carp::croak(@_);
260}
261
0d863452 2621;