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