This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[win32] merge changes#755..759,763,764 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
109=head1 AUTHOR
110
111Tom Phoenix, E<lt>F<rootbeer@teleport.com>E<gt>, with help from
112many other folks.
113
114=head1 COPYRIGHT
115
116Copyright (C) 1997, Tom Phoenix
117
118This module is free software; you can redistribute it or modify it
119under the same terms as Perl itself.
120
121=cut
122
123use strict;
124use Carp;
125use vars qw($VERSION);
126
127#=======================================================================
128
129# Some of this stuff didn't work in version 5.003, alas.
7e5dee47 130require 5.003_96;
54310121
PP
131
132#=======================================================================
133# import() - import symbols into user's namespace
134#
135# What we actually do is define a function in the caller's namespace
136# which returns the value. The function we create will normally
137# be inlined as a constant, thereby avoiding further sub calling
138# overhead.
139#=======================================================================
140sub import {
141 my $class = shift;
142 my $name = shift or return; # Ignore 'use constant;'
143 croak qq{Can't define "$name" as constant} .
144 qq{ (name contains invalid characters or is empty)}
145 unless $name =~ /^[^\W_0-9]\w*$/;
146
147 my $pkg = caller;
148 {
149 no strict 'refs';
150 if (@_ == 1) {
151 my $scalar = $_[0];
152 *{"${pkg}::$name"} = sub () { $scalar };
153 } elsif (@_) {
154 my @list = @_;
155 *{"${pkg}::$name"} = sub () { @list };
156 } else {
157 *{"${pkg}::$name"} = sub () { };
158 }
159 }
160
161}
162
1631;