This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[DOC PATCH bleadperl] perlport.pod and C<..">>"...>
[perl5.git] / lib / constant.pm
CommitLineData
54310121
PP
1package constant;
2
83763826 3use strict;
17f410f9 4use 5.005_64;
d3a7d8c7 5use warnings::register;
17f410f9
GS
6
7our($VERSION, %declared);
d6a466d7 8$VERSION = '1.03';
83763826
GS
9
10#=======================================================================
11
83763826 12# Some names are evil choices.
7d30b5c4 13my %keywords = map +($_, 1), qw{ BEGIN INIT CHECK END DESTROY AUTOLOAD };
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
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#=======================================================================
28sub import {
29 my $class = shift;
30 return unless @_; # Ignore 'use constant;'
3cb88d13
CT
31 my %constants = ();
32 my $multiple = ref $_[0];
33
34 if ( $multiple ) {
35 if (ref $_[0] ne 'HASH') {
36 require Carp;
37 Carp::croak("Invalid reference type '".ref(shift)."' not 'HASH'");
38 }
39 %constants = %{+shift};
40 } else {
41 $constants{+shift} = undef;
83763826 42 }
3cb88d13
CT
43
44 foreach my $name ( keys %constants ) {
45 unless (defined $name) {
46 require Carp;
47 Carp::croak("Can't use undef as constant name");
48 }
49 my $pkg = caller;
50
51 # Normal constant name
52 if ($name =~ /^_?[^\W_0-9]\w*\z/ and !$forbidden{$name}) {
53 # Everything is okay
54
55 # Name forced into main, but we're not in main. Fatal.
56 } elsif ($forced_into_main{$name} and $pkg ne 'main') {
57 require Carp;
58 Carp::croak("Constant name '$name' is forced into main::");
59
60 # Starts with double underscore. Fatal.
61 } elsif ($name =~ /^__/) {
62 require Carp;
63 Carp::croak("Constant name '$name' begins with '__'");
64
65 # Maybe the name is tolerable
66 } elsif ($name =~ /^[A-Za-z_]\w*\z/) {
67 # Then we'll warn only if you've asked for warnings
68 if (warnings::enabled()) {
69 if ($keywords{$name}) {
70 warnings::warn("Constant name '$name' is a Perl keyword");
71 } elsif ($forced_into_main{$name}) {
72 warnings::warn("Constant name '$name' is " .
73 "forced into package main::");
74 } else {
75 # Catch-all - what did I miss? If you get this error,
76 # please let me know what your constant's name was.
77 # Write to <rootbeer@redcat.com>. Thanks!
78 warnings::warn("Constant name '$name' has unknown problems");
79 }
80 }
81
82 # Looks like a boolean
83 # use constant FRED == fred;
84 } elsif ($name =~ /^[01]?\z/) {
85 require Carp;
86 if (@_) {
87 Carp::croak("Constant name '$name' is invalid");
83763826 88 } else {
3cb88d13 89 Carp::croak("Constant name looks like boolean value");
83763826 90 }
83763826 91
83763826 92 } else {
3cb88d13
CT
93 # Must have bad characters
94 require Carp;
95 Carp::croak("Constant name '$name' has invalid characters");
83763826
GS
96 }
97
3cb88d13
CT
98 {
99 no strict 'refs';
100 my $full_name = "${pkg}::$name";
101 $declared{$full_name}++;
102 if ($multiple) {
103 my $scalar = $constants{$name};
104 *$full_name = sub () { $scalar };
105 } else {
106 if (@_ == 1) {
107 my $scalar = $_[0];
108 *$full_name = sub () { $scalar };
109 } elsif (@_) {
110 my @list = @_;
111 *$full_name = sub () { @list };
112 } else {
113 *$full_name = sub () { };
114 }
115 }
83763826
GS
116 }
117 }
83763826
GS
118}
119
1201;
121
122__END__
54310121
PP
123
124=head1 NAME
125
126constant - Perl pragma to declare constants
127
128=head1 SYNOPSIS
129
130 use constant BUFFER_SIZE => 4096;
131 use constant ONE_YEAR => 365.2425 * 24 * 60 * 60;
132 use constant PI => 4 * atan2 1, 1;
133 use constant DEBUGGING => 0;
134 use constant ORACLE => 'oracle@cs.indiana.edu';
135 use constant USERNAME => scalar getpwuid($<);
136 use constant USERINFO => getpwuid($<);
137
138 sub deg2rad { PI * $_[0] / 180 }
139
140 print "This line does nothing" unless DEBUGGING;
141
83763826 142 # references can be constants
779c5bc9
GS
143 use constant CHASH => { foo => 42 };
144 use constant CARRAY => [ 1,2,3,4 ];
145 use constant CPSEUDOHASH => [ { foo => 1}, 42 ];
146 use constant CCODE => sub { "bite $_[0]\n" };
147
148 print CHASH->{foo};
149 print CARRAY->[$i];
150 print CPSEUDOHASH->{foo};
151 print CCODE->("me");
83763826 152 print CHASH->[10]; # compile-time error
779c5bc9 153
3cb88d13
CT
154 # declaring multiple constants at once
155 use constant {
156 BUFFER_SIZE => 4096,
157 ONE_YEAR => 365.2425 * 24 * 60 * 60,
158 PI => 4 * atan2( 1, 1 ),
159 DEBUGGING => 0,
160 ORACLE => 'oracle@cs.indiana.edu',
161 USERNAME => scalar getpwuid($<),
162 USERINFO => getpwuid($<),
163 };
164
54310121
PP
165=head1 DESCRIPTION
166
167This will declare a symbol to be a constant with the given scalar
168or list value.
169
170When you declare a constant such as C<PI> using the method shown
171above, each machine your script runs upon can have as many digits
172of accuracy as it can use. Also, your program will be easier to
173read, more likely to be maintained (and maintained correctly), and
174far less likely to send a space probe to the wrong planet because
175nobody noticed the one equation in which you wrote C<3.14195>.
176
177=head1 NOTES
178
179The value or values are evaluated in a list context. You may override
180this with C<scalar> as shown above.
181
182These constants do not directly interpolate into double-quotish
183strings, although you may do so indirectly. (See L<perlref> for
184details about how this works.)
185
186 print "The value of PI is @{[ PI ]}.\n";
187
188List constants are returned as lists, not as arrays.
189
190 $homedir = USERINFO[7]; # WRONG
191 $homedir = (USERINFO)[7]; # Right
192
193The use of all caps for constant names is merely a convention,
194although it is recommended in order to make constants stand out
195and to help avoid collisions with other barewords, keywords, and
83763826
GS
196subroutine names. Constant names must begin with a letter or
197underscore. Names beginning with a double underscore are reserved. Some
198poor choices for names will generate warnings, if warnings are enabled at
199compile time.
54310121
PP
200
201Constant symbols are package scoped (rather than block scoped, as
202C<use strict> is). That is, you can refer to a constant from package
203Other as C<Other::CONST>.
204
205As with all C<use> directives, defining a constant happens at
206compile time. Thus, it's probably not correct to put a constant
207declaration inside of a conditional statement (like C<if ($foo)
3cb88d13
CT
208{ use constant ... }>). When defining multiple constants, you
209cannot use the values of other constants within the same declaration
210scope. This is because the calling package doesn't know about any
211constant within that group until I<after> the C<use> statement is
212finished.
213
214 use constant {
215 AGE => 20,
216 PERSON => { age => AGE }, # Error!
217 };
218 [...]
219 use constant PERSON => { age => AGE }; # Right
54310121
PP
220
221Omitting the value for a symbol gives it the value of C<undef> in
222a scalar context or the empty list, C<()>, in a list context. This
223isn't so nice as it may sound, though, because in this case you
224must either quote the symbol name, or use a big arrow, (C<=E<gt>>),
3cb88d13
CT
225with nothing to point to. It is also illegal to do when defining
226multiple constants at once, you must declare them explicitly. It
227is probably best to declare these explicitly.
54310121
PP
228
229 use constant UNICORNS => ();
230 use constant LOGFILE => undef;
231
232The result from evaluating a list constant in a scalar context is
233not documented, and is B<not> guaranteed to be any particular value
234in the future. In particular, you should not rely upon it being
235the number of elements in the list, especially since it is not
236B<necessarily> that value in the current implementation.
237
238Magical values, tied values, and references can be made into
239constants at compile time, allowing for way cool stuff like this.
7e5dee47 240(These error numbers aren't totally portable, alas.)
54310121
PP
241
242 use constant E2BIG => ($! = 7);
243 print E2BIG, "\n"; # something like "Arg list too long"
244 print 0+E2BIG, "\n"; # "7"
245
83763826
GS
246Dereferencing constant references incorrectly (such as using an array
247subscript on a constant hash reference, or vice versa) will be trapped at
248compile time.
249
3cb88d13
CT
250When declaring multiple constants, all constant values will be a scalar.
251This is because C<constant> can't guess the intent of the programmer
252correctly all the time since values must be expressed in scalar context
253within a hash ref.
254
83763826
GS
255In the rare case in which you need to discover at run time whether a
256particular constant has been declared via this module, you may use
257this function to examine the hash C<%constant::declared>. If the given
258constant name does not include a package name, the current package is
259used.
260
261 sub declared ($) {
262 use constant 1.01; # don't omit this!
263 my $name = shift;
264 $name =~ s/^::/main::/;
265 my $pkg = caller;
266 my $full_name = $name =~ /::/ ? $name : "${pkg}::$name";
267 $constant::declared{$full_name};
268 }
779c5bc9 269
54310121
PP
270=head1 TECHNICAL NOTE
271
272In the current implementation, scalar constants are actually
273inlinable subroutines. As of version 5.004 of Perl, the appropriate
274scalar constant is inserted directly in place of some subroutine
275calls, thereby saving the overhead of a subroutine call. See
276L<perlsub/"Constant Functions"> for details about how and when this
277happens.
278
279=head1 BUGS
280
281In the current version of Perl, list constants are not inlined
282and some symbols may be redefined without generating a warning.
283
284It is not possible to have a subroutine or keyword with the same
83763826
GS
285name as a constant in the same package. This is probably a Good Thing.
286
287A constant with a name in the list C<STDIN STDOUT STDERR ARGV ARGVOUT
288ENV INC SIG> is not allowed anywhere but in package C<main::>, for
289technical reasons.
290
291Even though a reference may be declared as a constant, the reference may
292point to data which may be changed, as this code shows.
293
294 use constant CARRAY => [ 1,2,3,4 ];
295 print CARRAY->[1];
296 CARRAY->[1] = " be changed";
297 print CARRAY->[1];
54310121
PP
298
299Unlike constants in some languages, these cannot be overridden
300on the command line or via environment variables.
301
a3cb178b
GS
302You can get into trouble if you use constants in a context which
303automatically quotes barewords (as is true for any subroutine call).
304For example, you can't say C<$hash{CONSTANT}> because C<CONSTANT> will
305be interpreted as a string. Use C<$hash{CONSTANT()}> or
306C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from
307kicking in. Similarly, since the C<=E<gt>> operator quotes a bareword
83763826
GS
308immediately to its left, you have to say C<CONSTANT() =E<gt> 'value'>
309(or simply use a comma in place of the big arrow) instead of
310C<CONSTANT =E<gt> 'value'>.
a3cb178b 311
54310121
PP
312=head1 AUTHOR
313
83763826 314Tom Phoenix, E<lt>F<rootbeer@redcat.com>E<gt>, with help from
54310121
PP
315many other folks.
316
e1e60e72
CW
317Multiple constant declarations at once added by Casey West,
318E<lt>F<casey@geeknest.com>E<gt>.
3cb88d13 319
54310121
PP
320=head1 COPYRIGHT
321
83763826 322Copyright (C) 1997, 1999 Tom Phoenix
54310121
PP
323
324This module is free software; you can redistribute it or modify it
325under the same terms as Perl itself.
326
327=cut