Filename	/usr/lib64/perl5/5.16.0/feature.pm
Statements	Executed 32 statements in 388µs

Subroutines

Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
1	1	1	169µs	169µs	feature::::__commonfeature::__common
1	1	1	56µs	225µs	feature::::importfeature::import
0	0	0	0s	0s	feature::::croakfeature::croak
0	0	0	0s	0s	feature::::unimportfeature::unimport
0	0	0	0s	0s	feature::::unknown_featurefeature::unknown_feature
0	0	0	0s	0s	feature::::unknown_feature_bundlefeature::unknown_feature_bundle

Call graph for these subroutines as a Graphviz dot language file.

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 sub import {
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 sub __common {
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: