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