Filename | /usr/lib64/perl5/5.16.0/feature.pm |
Statements | Executed 32 statements in 388µs |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
1 | 1 | 1 | 169µs | 169µs | __common | feature::
1 | 1 | 1 | 56µs | 225µs | import | feature::
0 | 0 | 0 | 0s | 0s | croak | feature::
0 | 0 | 0 | 0s | 0s | unimport | feature::
0 | 0 | 0 | 0s | 0s | unknown_feature | feature::
0 | 0 | 0 | 0s | 0s | unknown_feature_bundle | feature::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
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 | 4µs | our $VERSION = '1.27'; | ||
9 | |||||
10 | 1 | 32µ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 | 40µ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 | 4µs | $feature_bundle{"5.12"} = $feature_bundle{"5.11"}; | ||
31 | 1 | 2µs | $feature_bundle{"5.13"} = $feature_bundle{"5.11"}; | ||
32 | 1 | 2µs | $feature_bundle{"5.14"} = $feature_bundle{"5.11"}; | ||
33 | 1 | 2µs | $feature_bundle{"5.16"} = $feature_bundle{"5.15"}; | ||
34 | 1 | 2µs | $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"}; | ||
35 | |||||
36 | 1 | 2µs | our $hint_shift = 26; | ||
37 | 1 | 800ns | our $hint_mask = 0x1c000000; | ||
38 | 1 | 8µ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 | 800ns | 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 | # spent 225µs (56+169) within feature::import which was called:
# once (56µs+169µs) by File::Glob::BEGIN@7 at line 7 of File/Glob.pm | ||||
303 | 1 | 4µs | my $class = shift; | ||
304 | |||||
305 | 1 | 2µs | if (!@_) { | ||
306 | croak("No features specified"); | ||||
307 | } | ||||
308 | |||||
309 | 1 | 29µs | 1 | 169µs | __common(1, @_); # spent 169µs making 1 call to feature::__common |
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 | # spent 169µs within feature::__common which was called:
# once (169µs+0s) by feature::import at line 309 | ||||
326 | 1 | 3µs | my $import = shift; | ||
327 | 1 | 6µs | my $bundle_number = $^H & $hint_mask; | ||
328 | 1 | 7µs | my $features = $bundle_number != $hint_mask | ||
329 | && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]}; | ||||
330 | 1 | 4µs | if ($features) { | ||
331 | # Features are enabled implicitly via bundle hints. | ||||
332 | # Delete any keys that may be left over from last time. | ||||
333 | 1 | 77µs | delete @^H{ values(%feature) }; | ||
334 | 1 | 4µs | $^H |= $hint_mask; | ||
335 | 1 | 6µs | for (@$features) { | ||
336 | 1 | 12µs | $^H{$feature{$_}} = 1; | ||
337 | 1 | 10µs | $^H |= $hint_uni8bit if $_ eq 'unicode_strings'; | ||
338 | } | ||||
339 | } | ||||
340 | 1 | 39µs | while (@_) { | ||
341 | 1 | 3µs | my $name = shift; | ||
342 | 1 | 5µs | 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 | 1 | 3µs | if (!exists $feature{$name}) { | ||
354 | unknown_feature($name); | ||||
355 | } | ||||
356 | 1 | 5µs | if ($import) { | ||
357 | 1 | 11µs | $^H{$feature{$name}} = 1; | ||
358 | 1 | 2µs | $^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 | 59µs | 1; | ||
384 | |||||
385 | # ex: set ro: |