Commit | Line | Data |
---|---|---|
54310121 | 1 | package constant; |
2 | ||
3 | $VERSION = '1.00'; | |
4 | ||
5 | =head1 NAME | |
6 | ||
7 | constant - 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 | ||
25 | This will declare a symbol to be a constant with the given scalar | |
26 | or list value. | |
27 | ||
28 | When you declare a constant such as C<PI> using the method shown | |
29 | above, each machine your script runs upon can have as many digits | |
30 | of accuracy as it can use. Also, your program will be easier to | |
31 | read, more likely to be maintained (and maintained correctly), and | |
32 | far less likely to send a space probe to the wrong planet because | |
33 | nobody noticed the one equation in which you wrote C<3.14195>. | |
34 | ||
35 | =head1 NOTES | |
36 | ||
37 | The value or values are evaluated in a list context. You may override | |
38 | this with C<scalar> as shown above. | |
39 | ||
40 | These constants do not directly interpolate into double-quotish | |
41 | strings, although you may do so indirectly. (See L<perlref> for | |
42 | details about how this works.) | |
43 | ||
44 | print "The value of PI is @{[ PI ]}.\n"; | |
45 | ||
46 | List constants are returned as lists, not as arrays. | |
47 | ||
48 | $homedir = USERINFO[7]; # WRONG | |
49 | $homedir = (USERINFO)[7]; # Right | |
50 | ||
51 | The use of all caps for constant names is merely a convention, | |
52 | although it is recommended in order to make constants stand out | |
53 | and to help avoid collisions with other barewords, keywords, and | |
54 | subroutine names. Constant names must begin with a letter. | |
55 | ||
56 | Constant symbols are package scoped (rather than block scoped, as | |
57 | C<use strict> is). That is, you can refer to a constant from package | |
58 | Other as C<Other::CONST>. | |
59 | ||
60 | As with all C<use> directives, defining a constant happens at | |
61 | compile time. Thus, it's probably not correct to put a constant | |
62 | declaration inside of a conditional statement (like C<if ($foo) | |
63 | { use constant ... }>). | |
64 | ||
65 | Omitting the value for a symbol gives it the value of C<undef> in | |
66 | a scalar context or the empty list, C<()>, in a list context. This | |
67 | isn't so nice as it may sound, though, because in this case you | |
68 | must either quote the symbol name, or use a big arrow, (C<=E<gt>>), | |
69 | with nothing to point to. It is probably best to declare these | |
70 | explicitly. | |
71 | ||
72 | use constant UNICORNS => (); | |
73 | use constant LOGFILE => undef; | |
74 | ||
75 | The result from evaluating a list constant in a scalar context is | |
76 | not documented, and is B<not> guaranteed to be any particular value | |
77 | in the future. In particular, you should not rely upon it being | |
78 | the number of elements in the list, especially since it is not | |
79 | B<necessarily> that value in the current implementation. | |
80 | ||
81 | Magical values, tied values, and references can be made into | |
82 | constants at compile time, allowing for way cool stuff like this. | |
7e5dee47 | 83 | (These error numbers aren't totally portable, alas.) |
54310121 | 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 | ||
91 | In the current implementation, scalar constants are actually | |
92 | inlinable subroutines. As of version 5.004 of Perl, the appropriate | |
93 | scalar constant is inserted directly in place of some subroutine | |
94 | calls, thereby saving the overhead of a subroutine call. See | |
95 | L<perlsub/"Constant Functions"> for details about how and when this | |
96 | happens. | |
97 | ||
98 | =head1 BUGS | |
99 | ||
100 | In the current version of Perl, list constants are not inlined | |
101 | and some symbols may be redefined without generating a warning. | |
102 | ||
103 | It is not possible to have a subroutine or keyword with the same | |
104 | name as a constant. This is probably a Good Thing. | |
105 | ||
106 | Unlike constants in some languages, these cannot be overridden | |
107 | on the command line or via environment variables. | |
108 | ||
a3cb178b GS |
109 | You can get into trouble if you use constants in a context which |
110 | automatically quotes barewords (as is true for any subroutine call). | |
111 | For example, you can't say C<$hash{CONSTANT}> because C<CONSTANT> will | |
112 | be interpreted as a string. Use C<$hash{CONSTANT()}> or | |
113 | C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from | |
114 | kicking in. Similarly, since the C<=E<gt>> operator quotes a bareword | |
115 | immediately to its left you have to say C<CONSTANT() =E<gt> 'value'> | |
116 | instead of C<CONSTANT =E<gt> 'value'>. | |
117 | ||
54310121 | 118 | =head1 AUTHOR |
119 | ||
120 | Tom Phoenix, E<lt>F<rootbeer@teleport.com>E<gt>, with help from | |
121 | many other folks. | |
122 | ||
123 | =head1 COPYRIGHT | |
124 | ||
125 | Copyright (C) 1997, Tom Phoenix | |
126 | ||
127 | This module is free software; you can redistribute it or modify it | |
128 | under the same terms as Perl itself. | |
129 | ||
130 | =cut | |
131 | ||
132 | use strict; | |
133 | use Carp; | |
134 | use vars qw($VERSION); | |
135 | ||
136 | #======================================================================= | |
137 | ||
138 | # Some of this stuff didn't work in version 5.003, alas. | |
7e5dee47 | 139 | require 5.003_96; |
54310121 | 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 | #======================================================================= | |
149 | sub 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 | ||
172 | 1; |