This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[inseperable changes from patch from perl-5.003_95 to perl-5.003_86]
[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.
83
84 use constant E2BIG => ($! = 7);
85 print E2BIG, "\n"; # something like "Arg list too long"
86 print 0+E2BIG, "\n"; # "7"
87
88=head1 TECHNICAL NOTE
89
90In the current implementation, scalar constants are actually
91inlinable subroutines. As of version 5.004 of Perl, the appropriate
92scalar constant is inserted directly in place of some subroutine
93calls, thereby saving the overhead of a subroutine call. See
94L<perlsub/"Constant Functions"> for details about how and when this
95happens.
96
97=head1 BUGS
98
99In the current version of Perl, list constants are not inlined
100and some symbols may be redefined without generating a warning.
101
102It is not possible to have a subroutine or keyword with the same
103name as a constant. This is probably a Good Thing.
104
105Unlike constants in some languages, these cannot be overridden
106on the command line or via environment variables.
107
108=head1 AUTHOR
109
110Tom Phoenix, E<lt>F<rootbeer@teleport.com>E<gt>, with help from
111many other folks.
112
113=head1 COPYRIGHT
114
115Copyright (C) 1997, Tom Phoenix
116
117This module is free software; you can redistribute it or modify it
118under the same terms as Perl itself.
119
120=cut
121
122use strict;
123use Carp;
124use vars qw($VERSION);
125
126#=======================================================================
127
128# Some of this stuff didn't work in version 5.003, alas.
129require 5.003_20;
130
131#=======================================================================
132# import() - import symbols into user's namespace
133#
134# What we actually do is define a function in the caller's namespace
135# which returns the value. The function we create will normally
136# be inlined as a constant, thereby avoiding further sub calling
137# overhead.
138#=======================================================================
139sub import {
140 my $class = shift;
141 my $name = shift or return; # Ignore 'use constant;'
142 croak qq{Can't define "$name" as constant} .
143 qq{ (name contains invalid characters or is empty)}
144 unless $name =~ /^[^\W_0-9]\w*$/;
145
146 my $pkg = caller;
147 {
148 no strict 'refs';
149 if (@_ == 1) {
150 my $scalar = $_[0];
151 *{"${pkg}::$name"} = sub () { $scalar };
152 } elsif (@_) {
153 my @list = @_;
154 *{"${pkg}::$name"} = sub () { @list };
155 } else {
156 *{"${pkg}::$name"} = sub () { };
157 }
158 }
159
160}
161
1621;