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