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