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