This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[win32] merge changes#872,873 from maintbranch
[perl5.git] / lib / constant.pm
CommitLineData
54310121
PP
1package constant;
2
3$VERSION = '1.00';
4
5=head1 NAME
6
7constant - Perl pragma to declare constants
8
9=head1 SYNOPSIS
10
11 use constant BUFFER_SIZE => 4096;
12 use constant ONE_YEAR => 365.2425 * 24 * 60 * 60;
13 use constant PI => 4 * atan2 1, 1;
14 use constant DEBUGGING => 0;
15 use constant ORACLE => 'oracle@cs.indiana.edu';
16 use constant USERNAME => scalar getpwuid($<);
17 use constant USERINFO => getpwuid($<);
18
19 sub deg2rad { PI * $_[0] / 180 }
20
21 print "This line does nothing" unless DEBUGGING;
22
23=head1 DESCRIPTION
24
25This will declare a symbol to be a constant with the given scalar
26or list value.
27
28When you declare a constant such as C<PI> using the method shown
29above, each machine your script runs upon can have as many digits
30of accuracy as it can use. Also, your program will be easier to
31read, more likely to be maintained (and maintained correctly), and
32far less likely to send a space probe to the wrong planet because
33nobody noticed the one equation in which you wrote C<3.14195>.
34
35=head1 NOTES
36
37The value or values are evaluated in a list context. You may override
38this with C<scalar> as shown above.
39
40These constants do not directly interpolate into double-quotish
41strings, although you may do so indirectly. (See L<perlref> for
42details about how this works.)
43
44 print "The value of PI is @{[ PI ]}.\n";
45
46List constants are returned as lists, not as arrays.
47
48 $homedir = USERINFO[7]; # WRONG
49 $homedir = (USERINFO)[7]; # Right
50
51The use of all caps for constant names is merely a convention,
52although it is recommended in order to make constants stand out
53and to help avoid collisions with other barewords, keywords, and
54subroutine names. Constant names must begin with a letter.
55
56Constant symbols are package scoped (rather than block scoped, as
57C<use strict> is). That is, you can refer to a constant from package
58Other as C<Other::CONST>.
59
60As with all C<use> directives, defining a constant happens at
61compile time. Thus, it's probably not correct to put a constant
62declaration inside of a conditional statement (like C<if ($foo)
63{ use constant ... }>).
64
65Omitting the value for a symbol gives it the value of C<undef> in
66a scalar context or the empty list, C<()>, in a list context. This
67isn't so nice as it may sound, though, because in this case you
68must either quote the symbol name, or use a big arrow, (C<=E<gt>>),
69with nothing to point to. It is probably best to declare these
70explicitly.
71
72 use constant UNICORNS => ();
73 use constant LOGFILE => undef;
74
75The result from evaluating a list constant in a scalar context is
76not documented, and is B<not> guaranteed to be any particular value
77in the future. In particular, you should not rely upon it being
78the number of elements in the list, especially since it is not
79B<necessarily> that value in the current implementation.
80
81Magical values, tied values, and references can be made into
82constants at compile time, allowing for way cool stuff like this.
7e5dee47 83(These error numbers aren't totally portable, alas.)
54310121
PP
84
85 use constant E2BIG => ($! = 7);
86 print E2BIG, "\n"; # something like "Arg list too long"
87 print 0+E2BIG, "\n"; # "7"
88
89=head1 TECHNICAL NOTE
90
91In the current implementation, scalar constants are actually
92inlinable subroutines. As of version 5.004 of Perl, the appropriate
93scalar constant is inserted directly in place of some subroutine
94calls, thereby saving the overhead of a subroutine call. See
95L<perlsub/"Constant Functions"> for details about how and when this
96happens.
97
98=head1 BUGS
99
100In the current version of Perl, list constants are not inlined
101and some symbols may be redefined without generating a warning.
102
103It is not possible to have a subroutine or keyword with the same
104name as a constant. This is probably a Good Thing.
105
106Unlike constants in some languages, these cannot be overridden
107on the command line or via environment variables.
108
a3cb178b
GS
109You can get into trouble if you use constants in a context which
110automatically quotes barewords (as is true for any subroutine call).
111For example, you can't say C<$hash{CONSTANT}> because C<CONSTANT> will
112be interpreted as a string. Use C<$hash{CONSTANT()}> or
113C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from
114kicking in. Similarly, since the C<=E<gt>> operator quotes a bareword
115immediately to its left you have to say C<CONSTANT() =E<gt> 'value'>
116instead of C<CONSTANT =E<gt> 'value'>.
117
54310121
PP
118=head1 AUTHOR
119
120Tom Phoenix, E<lt>F<rootbeer@teleport.com>E<gt>, with help from
121many other folks.
122
123=head1 COPYRIGHT
124
125Copyright (C) 1997, Tom Phoenix
126
127This module is free software; you can redistribute it or modify it
128under the same terms as Perl itself.
129
130=cut
131
132use strict;
133use Carp;
134use vars qw($VERSION);
135
136#=======================================================================
137
138# Some of this stuff didn't work in version 5.003, alas.
7e5dee47 139require 5.003_96;
54310121
PP
140
141#=======================================================================
142# import() - import symbols into user's namespace
143#
144# What we actually do is define a function in the caller's namespace
145# which returns the value. The function we create will normally
146# be inlined as a constant, thereby avoiding further sub calling
147# overhead.
148#=======================================================================
149sub import {
150 my $class = shift;
151 my $name = shift or return; # Ignore 'use constant;'
152 croak qq{Can't define "$name" as constant} .
153 qq{ (name contains invalid characters or is empty)}
154 unless $name =~ /^[^\W_0-9]\w*$/;
155
156 my $pkg = caller;
157 {
158 no strict 'refs';
159 if (@_ == 1) {
160 my $scalar = $_[0];
161 *{"${pkg}::$name"} = sub () { $scalar };
162 } elsif (@_) {
163 my @list = @_;
164 *{"${pkg}::$name"} = sub () { @list };
165 } else {
166 *{"${pkg}::$name"} = sub () { };
167 }
168 }
169
170}
171
1721;