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