File | /usr/local/lib/perl5/5.10.1/constant.pm |
Statements Executed | 2732 |
Statement Execution Time | 4.29ms |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
118 | 114 | 12 | 3.06ms | 3.73ms | import | constant::
118 | 1 | 2 | 272µs | 272µs | CORE:match (opcode) | constant::
118 | 1 | 2 | 89µs | 89µs | CORE:regcomp (opcode) | constant::
1 | 1 | 1 | 47µs | 47µs | BEGIN@2 | constant::
1 | 1 | 1 | 8µs | 81µs | BEGIN@4 | constant::
1 | 1 | 1 | 7µs | 19µs | BEGIN@38 | constant::
1 | 1 | 1 | 7µs | 17µs | BEGIN@101 | constant::
1 | 1 | 1 | 6µs | 43µs | BEGIN@6 | constant::
1 | 1 | 1 | 6µs | 9µs | BEGIN@3 | constant::
0 | 0 | 0 | 0s | 0s | __ANON__[:115] | constant::
0 | 0 | 0 | 0s | 0s | __ANON__[:119] | constant::
0 | 0 | 0 | 0s | 0s | __ANON__[:121] | constant::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | package constant; | ||||
2 | 3 | 60µs | 1 | 47µs | # spent 47µs within constant::BEGIN@2 which was called
# once (47µs+0s) by Class::MOP::Method::Generated::BEGIN@15 at line 2 # spent 47µs making 1 call to constant::BEGIN@2 |
3 | 3 | 25µs | 2 | 11µs | # spent 9µs (6+3) within constant::BEGIN@3 which was called
# once (6µs+3µs) by Class::MOP::Method::Generated::BEGIN@15 at line 3 # spent 9µs making 1 call to constant::BEGIN@3
# spent 2µs making 1 call to strict::import |
4 | 3 | 26µs | 2 | 154µs | # spent 81µs (8+73) within constant::BEGIN@4 which was called
# once (8µs+73µs) by Class::MOP::Method::Generated::BEGIN@15 at line 4 # spent 81µs making 1 call to constant::BEGIN@4
# spent 73µs making 1 call to warnings::register::import |
5 | |||||
6 | 3 | 108µs | 2 | 79µs | # spent 43µs (6+36) within constant::BEGIN@6 which was called
# once (6µs+36µs) by Class::MOP::Method::Generated::BEGIN@15 at line 6 # spent 43µs making 1 call to constant::BEGIN@6
# spent 36µs making 1 call to vars::import |
7 | 1 | 500ns | $VERSION = '1.17'; | ||
8 | |||||
9 | #======================================================================= | ||||
10 | |||||
11 | # Some names are evil choices. | ||||
12 | 1 | 6µs | my %keywords = map +($_, 1), qw{ BEGIN INIT CHECK END DESTROY AUTOLOAD }; | ||
13 | 1 | 2µs | $keywords{UNITCHECK}++ if $] > 5.009; | ||
14 | |||||
15 | 1 | 5µs | my %forced_into_main = map +($_, 1), | ||
16 | qw{ STDIN STDOUT STDERR ARGV ARGVOUT ENV INC SIG }; | ||||
17 | |||||
18 | 1 | 5µs | my %forbidden = (%keywords, %forced_into_main); | ||
19 | |||||
20 | #======================================================================= | ||||
21 | # import() - import symbols into user's namespace | ||||
22 | # | ||||
23 | # What we actually do is define a function in the caller's namespace | ||||
24 | # which returns the value. The function we create will normally | ||||
25 | # be inlined as a constant, thereby avoiding further sub calling | ||||
26 | # overhead. | ||||
27 | #======================================================================= | ||||
28 | # spent 3.73ms (3.06+667µs) within constant::import which was called 118 times, avg 32µs/call:
# 2 times (43µs+8µs) by UUID::Tiny::BEGIN@245 at line 245 of UUID/Tiny.pm, avg 26µs/call
# 2 times (41µs+8µs) by UUID::Tiny::BEGIN@246 at line 246 of UUID/Tiny.pm, avg 24µs/call
# 2 times (38µs+8µs) by UUID::Tiny::BEGIN@243 at line 243 of UUID/Tiny.pm, avg 23µs/call
# 2 times (38µs+7µs) by UUID::Tiny::BEGIN@244 at line 244 of UUID/Tiny.pm, avg 22µs/call
# once (90µs+18µs) by Compress::Raw::Zlib::BEGIN@70 at line 70 of Compress/Raw/Zlib.pm
# once (65µs+13µs) by Compress::Raw::Zlib::BEGIN@71 at line 71 of Compress/Raw/Zlib.pm
# once (34µs+26µs) by Class::MOP::Method::Generated::BEGIN@15 at line 15 of Class/MOP/Method/Generated.pm
# once (45µs+11µs) by IO::Compress::Gzip::Constants::BEGIN@65 at line 65 of IO/Compress/Gzip/Constants.pm
# once (41µs+12µs) by DateTime::TimeZone::BEGIN@17 at line 17 of DateTime/TimeZone.pm
# once (42µs+10µs) by Time::Local::BEGIN@28 at line 28 of Time/Local.pm
# once (41µs+9µs) by UUID::Tiny::BEGIN@200 at line 200 of UUID/Tiny.pm
# once (43µs+8µs) by IO::Compress::Gzip::Constants::BEGIN@78 at line 78 of IO/Compress/Gzip/Constants.pm
# once (42µs+8µs) by URI::_punycode::BEGIN@14 at line 14 of URI/_punycode.pm
# once (41µs+9µs) by JSON::Backend::XS::BEGIN@9 at line 9 of (eval 0)[JSON.pm:251] at line 251 of JSON.pm
# once (41µs+7µs) by Compress::Raw::Zlib::BEGIN@85 at line 85 of Compress/Raw/Zlib.pm
# once (35µs+8µs) by IO::Compress::Gzip::Constants::BEGIN@80 at line 80 of IO/Compress/Gzip/Constants.pm
# once (34µs+9µs) by Compress::Raw::Zlib::BEGIN@106 at line 106 of Compress/Raw/Zlib.pm
# once (35µs+8µs) by Compress::Raw::Zlib::BEGIN@101 at line 101 of Compress/Raw/Zlib.pm
# once (35µs+8µs) by Compress::Raw::Zlib::BEGIN@102 at line 102 of Compress/Raw/Zlib.pm
# once (35µs+7µs) by IO::Compress::Base::Common::BEGIN@41 at line 41 of IO/Compress/Base/Common.pm
# once (34µs+7µs) by IO::Compress::Gzip::Constants::BEGIN@77 at line 77 of IO/Compress/Gzip/Constants.pm
# once (35µs+6µs) by IO::Compress::Gzip::Constants::BEGIN@75 at line 75 of IO/Compress/Gzip/Constants.pm
# once (34µs+7µs) by Compress::Raw::Zlib::BEGIN@86 at line 86 of Compress/Raw/Zlib.pm
# once (33µs+8µs) by Compress::Raw::Zlib::BEGIN@83 at line 83 of Compress/Raw/Zlib.pm
# once (34µs+7µs) by Compress::Raw::Zlib::BEGIN@108 at line 108 of Compress/Raw/Zlib.pm
# once (33µs+7µs) by Compress::Raw::Zlib::BEGIN@87 at line 87 of Compress/Raw/Zlib.pm
# once (30µs+9µs) by DateTime::TimeZone::BEGIN@27 at line 27 of DateTime/TimeZone.pm
# once (31µs+7µs) by Compress::Raw::Zlib::BEGIN@84 at line 84 of Compress/Raw/Zlib.pm
# once (33µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@87 at line 87 of IO/Compress/Gzip/Constants.pm
# once (31µs+7µs) by Compress::Raw::Zlib::BEGIN@104 at line 104 of Compress/Raw/Zlib.pm
# once (31µs+7µs) by Compress::Raw::Zlib::BEGIN@110 at line 110 of Compress/Raw/Zlib.pm
# once (31µs+7µs) by IO::Compress::Gzip::Constants::BEGIN@76 at line 76 of IO/Compress/Gzip/Constants.pm
# once (30µs+7µs) by JSON::Backend::XS::BEGIN@11 at line 11 of (eval 0)[JSON.pm:251] at line 251 of JSON.pm
# once (30µs+5µs) by Compress::Raw::Zlib::BEGIN@112 at line 112 of Compress/Raw/Zlib.pm
# once (29µs+6µs) by Compress::Raw::Zlib::BEGIN@105 at line 105 of Compress/Raw/Zlib.pm
# once (29µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@115 at line 115 of IO/Compress/Gzip/Constants.pm
# once (29µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@109 at line 109 of IO/Compress/Gzip/Constants.pm
# once (27µs+6µs) by IO::Compress::Base::Common::BEGIN@461 at line 461 of IO/Compress/Base/Common.pm
# once (28µs+5µs) by IO::Compress::Base::Common::BEGIN@464 at line 464 of IO/Compress/Base/Common.pm
# once (26µs+6µs) by U64::BEGIN@818 at line 818 of IO/Compress/Base/Common.pm
# once (27µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@70 at line 70 of IO/Compress/Gzip/Constants.pm
# once (27µs+5µs) by IO::Compress::Base::Common::BEGIN@466 at line 466 of IO/Compress/Base/Common.pm
# once (26µs+5µs) by Compress::Raw::Zlib::BEGIN@111 at line 111 of Compress/Raw/Zlib.pm
# once (26µs+4µs) by U64::BEGIN@820 at line 820 of IO/Compress/Base/Common.pm
# once (25µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@143 at line 143 of IO/Compress/Gzip/Constants.pm
# once (24µs+5µs) by DateTime::Duration::BEGIN@22 at line 22 of DateTime/Duration.pm
# once (25µs+4µs) by IO::Uncompress::Base::BEGIN@15 at line 15 of IO/Uncompress/Base.pm
# once (25µs+5µs) by IO::Compress::Base::Common::BEGIN@131 at line 131 of IO/Compress/Base/Common.pm
# once (23µs+6µs) by DateTime::TimeZone::BEGIN@26 at line 26 of DateTime/TimeZone.pm
# once (24µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@82 at line 82 of IO/Compress/Gzip/Constants.pm
# once (23µs+5µs) by IO::Compress::Base::Common::BEGIN@130 at line 130 of IO/Compress/Base/Common.pm
# once (23µs+5µs) by Compress::Raw::Zlib::BEGIN@103 at line 103 of Compress/Raw/Zlib.pm
# once (23µs+6µs) by IO::Uncompress::Base::BEGIN@14 at line 14 of IO/Uncompress/Base.pm
# once (21µs+8µs) by IO::Compress::Base::Common::BEGIN@477 at line 477 of IO/Compress/Base/Common.pm
# once (22µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@88 at line 88 of IO/Compress/Gzip/Constants.pm
# once (22µs+6µs) by DateTime::BEGIN@68 at line 68 of DateTime.pm
# once (23µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@119 at line 119 of IO/Compress/Gzip/Constants.pm
# once (22µs+5µs) by IO::Compress::Base::Common::BEGIN@476 at line 476 of IO/Compress/Base/Common.pm
# once (22µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@66 at line 66 of IO/Compress/Gzip/Constants.pm
# once (25µs+2µs) by DateTime::BEGIN@70 at line 70 of DateTime.pm
# once (22µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@84 at line 84 of IO/Compress/Gzip/Constants.pm
# once (20µs+7µs) by DateTime::BEGIN@74 at line 74 of DateTime.pm
# once (22µs+5µs) by IO::Compress::Base::Common::BEGIN@462 at line 462 of IO/Compress/Base/Common.pm
# once (22µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@113 at line 113 of IO/Compress/Gzip/Constants.pm
# once (22µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@89 at line 89 of IO/Compress/Gzip/Constants.pm
# once (22µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@67 at line 67 of IO/Compress/Gzip/Constants.pm
# once (22µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@114 at line 114 of IO/Compress/Gzip/Constants.pm
# once (21µs+6µs) by DateTime::TimeZone::BEGIN@18 at line 18 of DateTime/TimeZone.pm
# once (22µs+4µs) by IO::Compress::Base::Common::BEGIN@471 at line 471 of IO/Compress/Base/Common.pm
# once (21µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@92 at line 92 of IO/Compress/Gzip/Constants.pm
# once (21µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@73 at line 73 of IO/Compress/Gzip/Constants.pm
# once (21µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@90 at line 90 of IO/Compress/Gzip/Constants.pm
# once (21µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@74 at line 74 of IO/Compress/Gzip/Constants.pm
# once (21µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@111 at line 111 of IO/Compress/Gzip/Constants.pm
# once (21µs+5µs) by IO::Compress::Base::Common::BEGIN@469 at line 469 of IO/Compress/Base/Common.pm
# once (21µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@86 at line 86 of IO/Compress/Gzip/Constants.pm
# once (21µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@69 at line 69 of IO/Compress/Gzip/Constants.pm
# once (22µs+4µs) by UUID::Tiny::BEGIN@215 at line 215 of UUID/Tiny.pm
# once (21µs+4µs) by Compress::Raw::Zlib::BEGIN@114 at line 114 of Compress/Raw/Zlib.pm
# once (21µs+4µs) by IO::Compress::Base::Common::BEGIN@463 at line 463 of IO/Compress/Base/Common.pm
# once (21µs+4µs) by IO::Compress::Base::Common::BEGIN@465 at line 465 of IO/Compress/Base/Common.pm
# once (21µs+4µs) by Compress::Raw::Zlib::BEGIN@115 at line 115 of Compress/Raw/Zlib.pm
# once (21µs+4µs) by Compress::Raw::Zlib::BEGIN@113 at line 113 of Compress/Raw/Zlib.pm
# once (21µs+4µs) by IO::Compress::Base::Common::BEGIN@470 at line 470 of IO/Compress/Base/Common.pm
# once (21µs+4µs) by U64::BEGIN@819 at line 819 of IO/Compress/Base/Common.pm
# once (20µs+5µs) by DateTime::TimeZone::BEGIN@23 at line 23 of DateTime/TimeZone.pm
# once (21µs+4µs) by Time::Local::BEGIN@30 at line 30 of Time/Local.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@473 at line 473 of IO/Compress/Base/Common.pm
# once (21µs+4µs) by JSON::Backend::XS::BEGIN@18 at line 18 of (eval 0)[JSON.pm:251] at line 251 of JSON.pm
# once (20µs+5µs) by DateTime::TimeZone::BEGIN@21 at line 21 of DateTime/TimeZone.pm
# once (20µs+5µs) by DateTime::TimeZone::BEGIN@22 at line 22 of DateTime/TimeZone.pm
# once (20µs+4µs) by DateTime::BEGIN@76 at line 76 of DateTime.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@42 at line 42 of IO/Compress/Base/Common.pm
# once (20µs+4µs) by Time::Local::BEGIN@29 at line 29 of Time/Local.pm
# once (19µs+5µs) by DateTime::TimeZone::BEGIN@25 at line 25 of DateTime/TimeZone.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@474 at line 474 of IO/Compress/Base/Common.pm
# once (20µs+4µs) by URI::_punycode::BEGIN@18 at line 18 of URI/_punycode.pm
# once (20µs+4µs) by UUID::Tiny::BEGIN@219 at line 219 of UUID/Tiny.pm
# once (20µs+4µs) by URI::_punycode::BEGIN@19 at line 19 of URI/_punycode.pm
# once (20µs+4µs) by URI::_punycode::BEGIN@16 at line 16 of URI/_punycode.pm
# once (19µs+5µs) by DateTime::TimeZone::BEGIN@24 at line 24 of DateTime/TimeZone.pm
# once (20µs+4µs) by UUID::Tiny::BEGIN@217 at line 217 of UUID/Tiny.pm
# once (20µs+4µs) by URI::_punycode::BEGIN@17 at line 17 of URI/_punycode.pm
# once (20µs+4µs) by URI::_punycode::BEGIN@15 at line 15 of URI/_punycode.pm
# once (20µs+4µs) by UUID::Tiny::BEGIN@221 at line 221 of UUID/Tiny.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@134 at line 134 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by IO::Compress::Base::Common::BEGIN@132 at line 132 of IO/Compress/Base/Common.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@43 at line 43 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by IO::Compress::Base::Common::BEGIN@478 at line 478 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by IO::Compress::Base::Common::BEGIN@475 at line 475 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by IO::Compress::Base::Common::BEGIN@44 at line 44 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by URI::_punycode::BEGIN@20 at line 20 of URI/_punycode.pm
# once (20µs+2µs) by DateTime::BEGIN@71 at line 71 of DateTime.pm
# once (20µs+2µs) by DateTime::BEGIN@72 at line 72 of DateTime.pm | ||||
29 | 118 | 59µs | my $class = shift; | ||
30 | 118 | 18µs | return unless @_; # Ignore 'use constant;' | ||
31 | 118 | 11µs | my $constants; | ||
32 | 118 | 33µs | my $multiple = ref $_[0]; | ||
33 | 118 | 41µs | my $pkg = caller; | ||
34 | 118 | 3µs | my $symtab; | ||
35 | 118 | 52µs | my $str_end = $] >= 5.006 ? "\\z" : "\\Z"; | ||
36 | |||||
37 | 118 | 46µs | if ($] > 5.009002) { | ||
38 | 3 | 211µs | 2 | 32µs | # spent 19µs (7+12) within constant::BEGIN@38 which was called
# once (7µs+12µs) by Class::MOP::Method::Generated::BEGIN@15 at line 38 # spent 19µs making 1 call to constant::BEGIN@38
# spent 12µs making 1 call to strict::unimport |
39 | 118 | 158µs | $symtab = \%{$pkg . '::'}; | ||
40 | }; | ||||
41 | |||||
42 | 118 | 19µs | if ( $multiple ) { | ||
43 | if (ref $_[0] ne 'HASH') { | ||||
44 | require Carp; | ||||
45 | Carp::croak("Invalid reference type '".ref(shift)."' not 'HASH'"); | ||||
46 | } | ||||
47 | $constants = shift; | ||||
48 | } else { | ||||
49 | 118 | 194µs | $constants->{+shift} = undef; | ||
50 | } | ||||
51 | |||||
52 | 118 | 663µs | foreach my $name ( keys %$constants ) { | ||
53 | 118 | 18µs | unless (defined $name) { | ||
54 | require Carp; | ||||
55 | Carp::croak("Can't use undef as constant name"); | ||||
56 | } | ||||
57 | |||||
58 | # Normal constant name | ||||
59 | 118 | 923µs | 236 | 361µs | if ($name =~ /^_?[^\W_0-9]\w*$str_end/ and !$forbidden{$name}) { # spent 272µs making 118 calls to constant::CORE:match, avg 2µs/call
# spent 89µs making 118 calls to constant::CORE:regcomp, avg 754ns/call |
60 | # Everything is okay | ||||
61 | |||||
62 | # Name forced into main, but we're not in main. Fatal. | ||||
63 | } elsif ($forced_into_main{$name} and $pkg ne 'main') { | ||||
64 | require Carp; | ||||
65 | Carp::croak("Constant name '$name' is forced into main::"); | ||||
66 | |||||
67 | # Starts with double underscore. Fatal. | ||||
68 | } elsif ($name =~ /^__/) { | ||||
69 | require Carp; | ||||
70 | Carp::croak("Constant name '$name' begins with '__'"); | ||||
71 | |||||
72 | # Maybe the name is tolerable | ||||
73 | } elsif ($name =~ /^[A-Za-z_]\w*$str_end/) { | ||||
74 | # Then we'll warn only if you've asked for warnings | ||||
75 | if (warnings::enabled()) { | ||||
76 | if ($keywords{$name}) { | ||||
77 | warnings::warn("Constant name '$name' is a Perl keyword"); | ||||
78 | } elsif ($forced_into_main{$name}) { | ||||
79 | warnings::warn("Constant name '$name' is " . | ||||
80 | "forced into package main::"); | ||||
81 | } | ||||
82 | } | ||||
83 | |||||
84 | # Looks like a boolean | ||||
85 | # use constant FRED == fred; | ||||
86 | } elsif ($name =~ /^[01]?$str_end/) { | ||||
87 | require Carp; | ||||
88 | if (@_) { | ||||
89 | Carp::croak("Constant name '$name' is invalid"); | ||||
90 | } else { | ||||
91 | Carp::croak("Constant name looks like boolean value"); | ||||
92 | } | ||||
93 | |||||
94 | } else { | ||||
95 | # Must have bad characters | ||||
96 | require Carp; | ||||
97 | Carp::croak("Constant name '$name' has invalid characters"); | ||||
98 | } | ||||
99 | |||||
100 | { | ||||
101 | 121 | 278µs | 2 | 28µs | # spent 17µs (7+11) within constant::BEGIN@101 which was called
# once (7µs+11µs) by Class::MOP::Method::Generated::BEGIN@15 at line 101 # spent 17µs making 1 call to constant::BEGIN@101
# spent 11µs making 1 call to strict::unimport |
102 | 118 | 78µs | my $full_name = "${pkg}::$name"; | ||
103 | 118 | 146µs | $declared{$full_name}++; | ||
104 | 118 | 80µs | if ($multiple || @_ == 1) { | ||
105 | 118 | 34µs | my $scalar = $multiple ? $constants->{$name} : $_[0]; | ||
106 | 118 | 77µs | if ($symtab && !exists $symtab->{$name}) { | ||
107 | # No typeglob yet, so we can use a reference as space- | ||||
108 | # efficient proxy for a constant subroutine | ||||
109 | # The check in Perl_ck_rvconst knows that inlinable | ||||
110 | # constants from cv_const_sv are read only. So we have to: | ||||
111 | 115 | 389µs | 115 | 124µs | Internals::SvREADONLY($scalar, 1); # spent 124µs making 115 calls to Internals::SvREADONLY, avg 1µs/call |
112 | 115 | 72µs | $symtab->{$name} = \$scalar; | ||
113 | 115 | 412µs | 115 | 181µs | mro::method_changed_in($pkg); # spent 181µs making 115 calls to mro::method_changed_in, avg 2µs/call |
114 | } else { | ||||
115 | 3 | 18µs | *$full_name = sub () { $scalar }; | ||
116 | } | ||||
117 | } elsif (@_) { | ||||
118 | my @list = @_; | ||||
119 | *$full_name = sub () { @list }; | ||||
120 | } else { | ||||
121 | *$full_name = sub () { }; | ||||
122 | } | ||||
123 | } | ||||
124 | } | ||||
125 | } | ||||
126 | |||||
127 | 1 | 17µs | 1; | ||
128 | |||||
129 | __END__ | ||||
130 | |||||
131 | =head1 NAME | ||||
132 | |||||
133 | constant - Perl pragma to declare constants | ||||
134 | |||||
135 | =head1 SYNOPSIS | ||||
136 | |||||
137 | use constant PI => 4 * atan2(1, 1); | ||||
138 | use constant DEBUG => 0; | ||||
139 | |||||
140 | print "Pi equals ", PI, "...\n" if DEBUG; | ||||
141 | |||||
142 | use constant { | ||||
143 | SEC => 0, | ||||
144 | MIN => 1, | ||||
145 | HOUR => 2, | ||||
146 | MDAY => 3, | ||||
147 | MON => 4, | ||||
148 | YEAR => 5, | ||||
149 | WDAY => 6, | ||||
150 | YDAY => 7, | ||||
151 | ISDST => 8, | ||||
152 | }; | ||||
153 | |||||
154 | use constant WEEKDAYS => qw( | ||||
155 | Sunday Monday Tuesday Wednesday Thursday Friday Saturday | ||||
156 | ); | ||||
157 | |||||
158 | print "Today is ", (WEEKDAYS)[ (localtime)[WDAY] ], ".\n"; | ||||
159 | |||||
160 | =head1 DESCRIPTION | ||||
161 | |||||
162 | This pragma allows you to declare constants at compile-time. | ||||
163 | |||||
164 | When you declare a constant such as C<PI> using the method shown | ||||
165 | above, each machine your script runs upon can have as many digits | ||||
166 | of accuracy as it can use. Also, your program will be easier to | ||||
167 | read, more likely to be maintained (and maintained correctly), and | ||||
168 | far less likely to send a space probe to the wrong planet because | ||||
169 | nobody noticed the one equation in which you wrote C<3.14195>. | ||||
170 | |||||
171 | When a constant is used in an expression, Perl replaces it with its | ||||
172 | value at compile time, and may then optimize the expression further. | ||||
173 | In particular, any code in an C<if (CONSTANT)> block will be optimized | ||||
174 | away if the constant is false. | ||||
175 | |||||
176 | =head1 NOTES | ||||
177 | |||||
178 | As with all C<use> directives, defining a constant happens at | ||||
179 | compile time. Thus, it's probably not correct to put a constant | ||||
180 | declaration inside of a conditional statement (like C<if ($foo) | ||||
181 | { use constant ... }>). | ||||
182 | |||||
183 | Constants defined using this module cannot be interpolated into | ||||
184 | strings like variables. However, concatenation works just fine: | ||||
185 | |||||
186 | print "Pi equals PI...\n"; # WRONG: does not expand "PI" | ||||
187 | print "Pi equals ".PI."...\n"; # right | ||||
188 | |||||
189 | Even though a reference may be declared as a constant, the reference may | ||||
190 | point to data which may be changed, as this code shows. | ||||
191 | |||||
192 | use constant ARRAY => [ 1,2,3,4 ]; | ||||
193 | print ARRAY->[1]; | ||||
194 | ARRAY->[1] = " be changed"; | ||||
195 | print ARRAY->[1]; | ||||
196 | |||||
197 | Dereferencing constant references incorrectly (such as using an array | ||||
198 | subscript on a constant hash reference, or vice versa) will be trapped at | ||||
199 | compile time. | ||||
200 | |||||
201 | Constants belong to the package they are defined in. To refer to a | ||||
202 | constant defined in another package, specify the full package name, as | ||||
203 | in C<Some::Package::CONSTANT>. Constants may be exported by modules, | ||||
204 | and may also be called as either class or instance methods, that is, | ||||
205 | as C<< Some::Package->CONSTANT >> or as C<< $obj->CONSTANT >> where | ||||
206 | C<$obj> is an instance of C<Some::Package>. Subclasses may define | ||||
207 | their own constants to override those in their base class. | ||||
208 | |||||
209 | The use of all caps for constant names is merely a convention, | ||||
210 | although it is recommended in order to make constants stand out | ||||
211 | and to help avoid collisions with other barewords, keywords, and | ||||
212 | subroutine names. Constant names must begin with a letter or | ||||
213 | underscore. Names beginning with a double underscore are reserved. Some | ||||
214 | poor choices for names will generate warnings, if warnings are enabled at | ||||
215 | compile time. | ||||
216 | |||||
217 | =head2 List constants | ||||
218 | |||||
219 | Constants may be lists of more (or less) than one value. A constant | ||||
220 | with no values evaluates to C<undef> in scalar context. Note that | ||||
221 | constants with more than one value do I<not> return their last value in | ||||
222 | scalar context as one might expect. They currently return the number | ||||
223 | of values, but B<this may change in the future>. Do not use constants | ||||
224 | with multiple values in scalar context. | ||||
225 | |||||
226 | B<NOTE:> This implies that the expression defining the value of a | ||||
227 | constant is evaluated in list context. This may produce surprises: | ||||
228 | |||||
229 | use constant TIMESTAMP => localtime; # WRONG! | ||||
230 | use constant TIMESTAMP => scalar localtime; # right | ||||
231 | |||||
232 | The first line above defines C<TIMESTAMP> as a 9-element list, as | ||||
233 | returned by C<localtime()> in list context. To set it to the string | ||||
234 | returned by C<localtime()> in scalar context, an explicit C<scalar> | ||||
235 | keyword is required. | ||||
236 | |||||
237 | List constants are lists, not arrays. To index or slice them, they | ||||
238 | must be placed in parentheses. | ||||
239 | |||||
240 | my @workdays = WEEKDAYS[1 .. 5]; # WRONG! | ||||
241 | my @workdays = (WEEKDAYS)[1 .. 5]; # right | ||||
242 | |||||
243 | =head2 Defining multiple constants at once | ||||
244 | |||||
245 | Instead of writing multiple C<use constant> statements, you may define | ||||
246 | multiple constants in a single statement by giving, instead of the | ||||
247 | constant name, a reference to a hash where the keys are the names of | ||||
248 | the constants to be defined. Obviously, all constants defined using | ||||
249 | this method must have a single value. | ||||
250 | |||||
251 | use constant { | ||||
252 | FOO => "A single value", | ||||
253 | BAR => "This", "won't", "work!", # Error! | ||||
254 | }; | ||||
255 | |||||
256 | This is a fundamental limitation of the way hashes are constructed in | ||||
257 | Perl. The error messages produced when this happens will often be | ||||
258 | quite cryptic -- in the worst case there may be none at all, and | ||||
259 | you'll only later find that something is broken. | ||||
260 | |||||
261 | When defining multiple constants, you cannot use the values of other | ||||
262 | constants defined in the same declaration. This is because the | ||||
263 | calling package doesn't know about any constant within that group | ||||
264 | until I<after> the C<use> statement is finished. | ||||
265 | |||||
266 | use constant { | ||||
267 | BITMASK => 0xAFBAEBA8, | ||||
268 | NEGMASK => ~BITMASK, # Error! | ||||
269 | }; | ||||
270 | |||||
271 | =head2 Magic constants | ||||
272 | |||||
273 | Magical values and references can be made into constants at compile | ||||
274 | time, allowing for way cool stuff like this. (These error numbers | ||||
275 | aren't totally portable, alas.) | ||||
276 | |||||
277 | use constant E2BIG => ($! = 7); | ||||
278 | print E2BIG, "\n"; # something like "Arg list too long" | ||||
279 | print 0+E2BIG, "\n"; # "7" | ||||
280 | |||||
281 | You can't produce a tied constant by giving a tied scalar as the | ||||
282 | value. References to tied variables, however, can be used as | ||||
283 | constants without any problems. | ||||
284 | |||||
285 | =head1 TECHNICAL NOTES | ||||
286 | |||||
287 | In the current implementation, scalar constants are actually | ||||
288 | inlinable subroutines. As of version 5.004 of Perl, the appropriate | ||||
289 | scalar constant is inserted directly in place of some subroutine | ||||
290 | calls, thereby saving the overhead of a subroutine call. See | ||||
291 | L<perlsub/"Constant Functions"> for details about how and when this | ||||
292 | happens. | ||||
293 | |||||
294 | In the rare case in which you need to discover at run time whether a | ||||
295 | particular constant has been declared via this module, you may use | ||||
296 | this function to examine the hash C<%constant::declared>. If the given | ||||
297 | constant name does not include a package name, the current package is | ||||
298 | used. | ||||
299 | |||||
300 | sub declared ($) { | ||||
301 | use constant 1.01; # don't omit this! | ||||
302 | my $name = shift; | ||||
303 | $name =~ s/^::/main::/; | ||||
304 | my $pkg = caller; | ||||
305 | my $full_name = $name =~ /::/ ? $name : "${pkg}::$name"; | ||||
306 | $constant::declared{$full_name}; | ||||
307 | } | ||||
308 | |||||
309 | =head1 CAVEATS | ||||
310 | |||||
311 | In the current version of Perl, list constants are not inlined | ||||
312 | and some symbols may be redefined without generating a warning. | ||||
313 | |||||
314 | It is not possible to have a subroutine or a keyword with the same | ||||
315 | name as a constant in the same package. This is probably a Good Thing. | ||||
316 | |||||
317 | A constant with a name in the list C<STDIN STDOUT STDERR ARGV ARGVOUT | ||||
318 | ENV INC SIG> is not allowed anywhere but in package C<main::>, for | ||||
319 | technical reasons. | ||||
320 | |||||
321 | Unlike constants in some languages, these cannot be overridden | ||||
322 | on the command line or via environment variables. | ||||
323 | |||||
324 | You can get into trouble if you use constants in a context which | ||||
325 | automatically quotes barewords (as is true for any subroutine call). | ||||
326 | For example, you can't say C<$hash{CONSTANT}> because C<CONSTANT> will | ||||
327 | be interpreted as a string. Use C<$hash{CONSTANT()}> or | ||||
328 | C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from | ||||
329 | kicking in. Similarly, since the C<< => >> operator quotes a bareword | ||||
330 | immediately to its left, you have to say C<< CONSTANT() => 'value' >> | ||||
331 | (or simply use a comma in place of the big arrow) instead of | ||||
332 | C<< CONSTANT => 'value' >>. | ||||
333 | |||||
334 | =head1 SEE ALSO | ||||
335 | |||||
336 | L<Readonly> - Facility for creating read-only scalars, arrays, hashes. | ||||
337 | |||||
338 | L<Const> - Facility for creating read-only variables. Similar to C<Readonly>, | ||||
339 | but uses C<SvREADONLY> instead of C<tie>. | ||||
340 | |||||
341 | L<Attribute::Constant> - Make read-only variables via attribute | ||||
342 | |||||
343 | L<Scalar::Readonly> - Perl extension to the C<SvREADONLY> scalar flag | ||||
344 | |||||
345 | L<Hash::Util> - A selection of general-utility hash subroutines (mostly | ||||
346 | to lock/unlock keys and values) | ||||
347 | |||||
348 | =head1 BUGS | ||||
349 | |||||
350 | Please report any bugs or feature requests via the perlbug(1) utility. | ||||
351 | |||||
352 | =head1 AUTHORS | ||||
353 | |||||
354 | Tom Phoenix, E<lt>F<rootbeer@redcat.com>E<gt>, with help from | ||||
355 | many other folks. | ||||
356 | |||||
357 | Multiple constant declarations at once added by Casey West, | ||||
358 | E<lt>F<casey@geeknest.com>E<gt>. | ||||
359 | |||||
360 | Documentation mostly rewritten by Ilmari Karonen, | ||||
361 | E<lt>F<perl@itz.pp.sci.fi>E<gt>. | ||||
362 | |||||
363 | This program is maintained by the Perl 5 Porters. | ||||
364 | The CPAN distribution is maintained by SE<eacute>bastien Aperghis-Tramoni | ||||
365 | E<lt>F<sebastien@aperghis.net>E<gt>. | ||||
366 | |||||
367 | =head1 COPYRIGHT & LICENSE | ||||
368 | |||||
369 | Copyright (C) 1997, 1999 Tom Phoenix | ||||
370 | |||||
371 | This module is free software; you can redistribute it or modify it | ||||
372 | under the same terms as Perl itself. | ||||
373 | |||||
374 | =cut | ||||
# spent 272µs within constant::CORE:match which was called 118 times, avg 2µs/call:
# 118 times (272µs+0s) by constant::import at line 59 of constant.pm, avg 2µs/call | |||||
# spent 89µs within constant::CORE:regcomp which was called 118 times, avg 754ns/call:
# 118 times (89µs+0s) by constant::import at line 59 of constant.pm, avg 754ns/call |