Fix [perl #114812] Configure not finding isblank().
[perl.git] / lib / feature.pm
1 # -*- buffer-read-only: t -*-
2 # !!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
3 # This file is built by regen/feature.pl.
4 # Any changes made here will be lost!
5
6 package feature;
7
8 our $VERSION = '1.29';
9
10 our %feature = (
11     fc              => 'feature_fc',
12     say             => 'feature_say',
13     state           => 'feature_state',
14     switch          => 'feature_switch',
15     evalbytes       => 'feature_evalbytes',
16     array_base      => 'feature_arybase',
17     current_sub     => 'feature___SUB__',
18     unicode_eval    => 'feature_unieval',
19     unicode_strings => 'feature_unicode',
20 );
21
22 our %feature_bundle = (
23     "5.10"    => [qw(array_base say state switch)],
24     "5.11"    => [qw(array_base say state switch unicode_strings)],
25     "5.15"    => [qw(current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
26     "all"     => [qw(array_base current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
27     "default" => [qw(array_base)],
28 );
29
30 $feature_bundle{"5.12"} = $feature_bundle{"5.11"};
31 $feature_bundle{"5.13"} = $feature_bundle{"5.11"};
32 $feature_bundle{"5.14"} = $feature_bundle{"5.11"};
33 $feature_bundle{"5.16"} = $feature_bundle{"5.15"};
34 $feature_bundle{"5.17"} = $feature_bundle{"5.15"};
35 $feature_bundle{"5.18"} = $feature_bundle{"5.15"};
36 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
37
38 our $hint_shift   = 26;
39 our $hint_mask    = 0x1c000000;
40 our @hint_bundles = qw( default 5.10 5.11 5.15 );
41
42 # This gets set (for now) in $^H as well as in %^H,
43 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
44 # See HINT_UNI_8_BIT in perl.h.
45 our $hint_uni8bit = 0x00000800;
46
47 # TODO:
48 # - think about versioned features (use feature switch => 2)
49
50 =head1 NAME
51
52 feature - Perl pragma to enable new features
53
54 =head1 SYNOPSIS
55
56     use feature qw(say switch);
57     given ($foo) {
58         when (1)          { say "\$foo == 1" }
59         when ([2,3])      { say "\$foo == 2 || \$foo == 3" }
60         when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
61         when ($_ > 100)   { say "\$foo > 100" }
62         default           { say "None of the above" }
63     }
64
65     use feature ':5.10'; # loads all features available in perl 5.10
66
67     use v5.10;           # implicitly loads :5.10 feature bundle
68
69 =head1 DESCRIPTION
70
71 It is usually impossible to add new syntax to Perl without breaking
72 some existing programs.  This pragma provides a way to minimize that
73 risk. New syntactic constructs, or new semantic meanings to older
74 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
75 only when the appropriate feature pragma is in scope.  (Nevertheless, the
76 C<CORE::> prefix provides access to all Perl keywords, regardless of this
77 pragma.)
78
79 =head2 Lexical effect
80
81 Like other pragmas (C<use strict>, for example), features have a lexical
82 effect. C<use feature qw(foo)> will only make the feature "foo" available
83 from that point to the end of the enclosing block.
84
85     {
86         use feature 'say';
87         say "say is available here";
88     }
89     print "But not here.\n";
90
91 =head2 C<no feature>
92
93 Features can also be turned off by using C<no feature "foo">.  This too
94 has lexical effect.
95
96     use feature 'say';
97     say "say is available here";
98     {
99         no feature 'say';
100         print "But not here.\n";
101     }
102     say "Yet it is here.";
103
104 C<no feature> with no features specified will reset to the default group.  To
105 disable I<all> features (an unusual request!) use C<no feature ':all'>.
106
107 =head1 AVAILABLE FEATURES
108
109 =head2 The 'say' feature
110
111 C<use feature 'say'> tells the compiler to enable the Perl 6 style
112 C<say> function.
113
114 See L<perlfunc/say> for details.
115
116 This feature is available starting with Perl 5.10.
117
118 =head2 The 'state' feature
119
120 C<use feature 'state'> tells the compiler to enable C<state>
121 variables.
122
123 See L<perlsub/"Persistent Private Variables"> for details.
124
125 This feature is available starting with Perl 5.10.
126
127 =head2 The 'switch' feature
128
129 C<use feature 'switch'> tells the compiler to enable the Perl 6
130 given/when construct.
131
132 See L<perlsyn/"Switch Statements"> for details.
133
134 This feature is available starting with Perl 5.10.
135
136 =head2 The 'unicode_strings' feature
137
138 C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
139 in all string operations executed within its scope (unless they are also
140 within the scope of either C<use locale> or C<use bytes>).  The same applies
141 to all regular expressions compiled within the scope, even if executed outside
142 it.  It does not change the internal representation of strings, but only how
143 they are interpreted.
144
145 C<no feature 'unicode_strings'> tells the compiler to use the traditional
146 Perl semantics wherein the native character set semantics is used unless it is
147 clear to Perl that Unicode is desired.  This can lead to some surprises
148 when the behavior suddenly changes.  (See
149 L<perlunicode/The "Unicode Bug"> for details.)  For this reason, if you are
150 potentially using Unicode in your program, the
151 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
152
153 This feature is available starting with Perl 5.12; was almost fully
154 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>.
155
156 =head2 The 'unicode_eval' and 'evalbytes' features
157
158 Under the C<unicode_eval> feature, Perl's C<eval> function, when passed a
159 string, will evaluate it as a string of characters, ignoring any
160 C<use utf8> declarations.  C<use utf8> exists to declare the encoding of
161 the script, which only makes sense for a stream of bytes, not a string of
162 characters.  Source filters are forbidden, as they also really only make
163 sense on strings of bytes.  Any attempt to activate a source filter will
164 result in an error.
165
166 The C<evalbytes> feature enables the C<evalbytes> keyword, which evaluates
167 the argument passed to it as a string of bytes.  It dies if the string
168 contains any characters outside the 8-bit range.  Source filters work
169 within C<evalbytes>: they apply to the contents of the string being
170 evaluated.
171
172 Together, these two features are intended to replace the historical C<eval>
173 function, which has (at least) two bugs in it, that cannot easily be fixed
174 without breaking existing programs:
175
176 =over
177
178 =item *
179
180 C<eval> behaves differently depending on the internal encoding of the
181 string, sometimes treating its argument as a string of bytes, and sometimes
182 as a string of characters.
183
184 =item *
185
186 Source filters activated within C<eval> leak out into whichever I<file>
187 scope is currently being compiled.  To give an example with the CPAN module
188 L<Semi::Semicolons>:
189
190     BEGIN { eval "use Semi::Semicolons;  # not filtered here " }
191     # filtered here!
192
193 C<evalbytes> fixes that to work the way one would expect:
194
195     use feature "evalbytes";
196     BEGIN { evalbytes "use Semi::Semicolons;  # filtered " }
197     # not filtered
198
199 =back
200
201 These two features are available starting with Perl 5.16.
202
203 =head2 The 'current_sub' feature
204
205 This provides the C<__SUB__> token that returns a reference to the current
206 subroutine or C<undef> outside of a subroutine.
207
208 This feature is available starting with Perl 5.16.
209
210 =head2 The 'array_base' feature
211
212 This feature supports the legacy C<$[> variable.  See L<perlvar/$[> and
213 L<arybase>.  It is on by default but disabled under C<use v5.16> (see
214 L</IMPLICIT LOADING>, below).
215
216 This feature is available under this name starting with Perl 5.16.  In
217 previous versions, it was simply on all the time, and this pragma knew
218 nothing about it.
219
220 =head2 The 'fc' feature
221
222 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
223 which implements Unicode casefolding.
224
225 See L<perlfunc/fc> for details.
226
227 This feature is available from Perl 5.16 onwards.
228
229 =head1 FEATURE BUNDLES
230
231 It's possible to load multiple features together, using
232 a I<feature bundle>.  The name of a feature bundle is prefixed with
233 a colon, to distinguish it from an actual feature.
234
235   use feature ":5.10";
236
237 The following feature bundles are available:
238
239   bundle    features included
240   --------- -----------------
241   :default  array_base
242
243   :5.10     say state switch array_base
244
245   :5.12     say state switch unicode_strings array_base
246
247   :5.14     say state switch unicode_strings array_base
248
249   :5.16     say state switch unicode_strings
250             unicode_eval evalbytes current_sub fc
251
252   :5.18     say state switch unicode_strings
253             unicode_eval evalbytes current_sub fc
254
255 The C<:default> bundle represents the feature set that is enabled before
256 any C<use feature> or C<no feature> declaration.
257
258 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
259 no effect.  Feature bundles are guaranteed to be the same for all sub-versions.
260
261   use feature ":5.14.0";    # same as ":5.14"
262   use feature ":5.14.1";    # same as ":5.14"
263
264 =head1 IMPLICIT LOADING
265
266 Instead of loading feature bundles by name, it is easier to let Perl do
267 implicit loading of a feature bundle for you.
268
269 There are two ways to load the C<feature> pragma implicitly:
270
271 =over 4
272
273 =item *
274
275 By using the C<-E> switch on the Perl command-line instead of C<-e>.
276 That will enable the feature bundle for that version of Perl in the
277 main compilation unit (that is, the one-liner that follows C<-E>).
278
279 =item *
280
281 By explicitly requiring a minimum Perl version number for your program, with
282 the C<use VERSION> construct.  That is,
283
284     use v5.10.0;
285
286 will do an implicit
287
288     no feature ':all';
289     use feature ':5.10';
290
291 and so on.  Note how the trailing sub-version
292 is automatically stripped from the
293 version.
294
295 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
296
297     use 5.010;
298
299 with the same effect.
300
301 If the required version is older than Perl 5.10, the ":default" feature
302 bundle is automatically loaded instead.
303
304 =back
305
306 =cut
307
308 sub import {
309     my $class = shift;
310
311     if (!@_) {
312         croak("No features specified");
313     }
314
315     __common(1, @_);
316 }
317
318 sub unimport {
319     my $class = shift;
320
321     # A bare C<no feature> should reset to the default bundle
322     if (!@_) {
323         $^H &= ~($hint_uni8bit|$hint_mask);
324         return;
325     }
326
327     __common(0, @_);
328 }
329
330
331 sub __common {
332     my $import = shift;
333     my $bundle_number = $^H & $hint_mask;
334     my $features = $bundle_number != $hint_mask
335         && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
336     if ($features) {
337         # Features are enabled implicitly via bundle hints.
338         # Delete any keys that may be left over from last time.
339         delete @^H{ values(%feature) };
340         $^H |= $hint_mask;
341         for (@$features) {
342             $^H{$feature{$_}} = 1;
343             $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
344         }
345     }
346     while (@_) {
347         my $name = shift;
348         if (substr($name, 0, 1) eq ":") {
349             my $v = substr($name, 1);
350             if (!exists $feature_bundle{$v}) {
351                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
352                 if (!exists $feature_bundle{$v}) {
353                     unknown_feature_bundle(substr($name, 1));
354                 }
355             }
356             unshift @_, @{$feature_bundle{$v}};
357             next;
358         }
359         if (!exists $feature{$name}) {
360             unknown_feature($name);
361         }
362         if ($import) {
363             $^H{$feature{$name}} = 1;
364             $^H |= $hint_uni8bit if $name eq 'unicode_strings';
365         } else {
366             delete $^H{$feature{$name}};
367             $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
368         }
369     }
370 }
371
372 sub unknown_feature {
373     my $feature = shift;
374     croak(sprintf('Feature "%s" is not supported by Perl %vd',
375             $feature, $^V));
376 }
377
378 sub unknown_feature_bundle {
379     my $feature = shift;
380     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
381             $feature, $^V));
382 }
383
384 sub croak {
385     require Carp;
386     Carp::croak(@_);
387 }
388
389 1;
390
391 # ex: set ro: